Paypal Name Value Pair Api 2012 Developers Guide Developer

Name-Value Pair API - 2012 - Developer Guide PP_NVPAPI_DG_2012 Free User Guide for PayPal Software, Manual

2015-07-27

: Paypal Paypal-Name-Value-Pair-Api-2012-Developers-Guide-777970 paypal-name-value-pair-api-2012-developers-guide-777970 paypal pdf

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

Name-Value Pair API
Developer Guide
Last updated: August 2012
Name-Value Pair API Developer Guide
Document Number: 100018.en_US-201208
© 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L-
2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Name-Value Pair API Developer Guide August 2012 3
Contents
What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
What’s New in Version 93.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 1 PayPal Name-Value Pair API Basics . . . . . . . . . . . . .15
PayPal API Client-Server Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
PayPal Name-Value Pair API Requests and Responses . . . . . . . . . . . . . . . . 16
UTF-8 Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Multiple API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
NVP Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Creating an NVP Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Specifying the PayPal API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Specifying an API Credential Using Signatures . . . . . . . . . . . . . . . . . . . . . 19
URL Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
List Syntax for Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Executing NVP API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Specifying a PayPal Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Logging API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Responding to an NVP Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Common Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
URL Decoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Chapter 2 AddressVerify API Operation . . . . . . . . . . . . . . . .25
AddressVerify Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Address Verify Request Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
AddressVerify Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Contents
4August 2012 Name-Value Pair API Developer Guide
Address Verify Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Chapter 3 Authorization and Capture API Operation Reference . . . .27
DoCapture API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
DoCapture Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
DoCapture Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
DoAuthorization API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
DoAuthorization Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
DoAuthorization Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . 33
DoReauthorization API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
DoReauthorization Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . 36
DoReauthorization Response Message . . . . . . . . . . . . . . . . . . . . . . . . . 37
DoVoid API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
DoVoid Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
DoVoid Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Chapter 4 DoDirectPayment API Operation . . . . . . . . . . . . . .41
DoDirectPayment Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
DoDirectPayment Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Credit Card Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Payer Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Payment Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Payment Details Item Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Ebay Item Payment Details Item Fields . . . . . . . . . . . . . . . . . . . . . . . . . 46
Ship To Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
3D Secure Request Fields (U.K. Merchants Only) . . . . . . . . . . . . . . . . . . . 47
DoDirectPayment Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
DoDirectPayment Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
ThreeDSecure Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Chapter 5 DoNonReferencedCredit API Operation . . . . . . . . . . .51
DoNonReferencedCredit Request Message . . . . . . . . . . . . . . . . . . . . . . . . . 51
DoNonReferencedCredit Request Fields . . . . . . . . . . . . . . . . . . . . . . . . 51
Credit Card Details Type Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Payer Name Type Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Payer Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Name-Value Pair API Developer Guide August 2012 5
Contents
DoNonReferencedCredit Response Message . . . . . . . . . . . . . . . . . . . . . . . . 54
DoNonReferencedCredit Response Fields . . . . . . . . . . . . . . . . . . . . . . . 54
Chapter 6 ExpressCheckout API Operations . . . . . . . . . . . . . .55
Callback API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Callback API Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Callback Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
SetExpressCheckout API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
SetExpressCheckout Request Message . . . . . . . . . . . . . . . . . . . . . . . . 59
SetExpressCheckout Response Message. . . . . . . . . . . . . . . . . . . . . . . . 78
GetExpressCheckoutDetails API Operation . . . . . . . . . . . . . . . . . . . . . . . . . 78
GetExpressCheckoutDetails Request Message. . . . . . . . . . . . . . . . . . . . . 78
GetExpressCheckoutDetails Response Message . . . . . . . . . . . . . . . . . . . . 79
DoExpressCheckoutPayment API Operation . . . . . . . . . . . . . . . . . . . . . . . . 92
DoExpressCheckoutPayment Request Message . . . . . . . . . . . . . . . . . . . . 92
DoExpressCheckoutPayment Response Message . . . . . . . . . . . . . . . . . . .105
Chapter 7 GetBalance API Operation. . . . . . . . . . . . . . . . . 117
GetBalance Request Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
GetBalance Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
GetBalance Response Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
GetBalance Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Chapter 8 GetPalDetails API Operation . . . . . . . . . . . . . . . 119
GetPalDetails Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
GetPalDetails Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
GetPalDetails Response Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
GetPalDetails Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Chapter 9 GetTransactionDetails API Operation . . . . . . . . . . . 121
GetTransactionDetails Request Message . . . . . . . . . . . . . . . . . . . . . . . . . .121
GetTransactionDetails Request Fields. . . . . . . . . . . . . . . . . . . . . . . . . .121
GetTransactionDetails Response Message . . . . . . . . . . . . . . . . . . . . . . . . .121
GetTransactionDetails Response Fields. . . . . . . . . . . . . . . . . . . . . . . . .121
Receiver Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Payer Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Payer Name Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Contents
6August 2012 Name-Value Pair API Developer Guide
Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Payment Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Payment Item Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Payment Item Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
Auction Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Subscription Terms Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Chapter 10 ManagePendingTransactionStatus API Operation . . . . . 133
ManagePendingTransactionStatus Request Message. . . . . . . . . . . . . . . . . . . .133
ManagePendingTransactionStatus Request Fields . . . . . . . . . . . . . . . . . . .133
ManagePendingTransactionStatus Response Message . . . . . . . . . . . . . . . . . .134
ManagePendingTransactionStatus Response Fields . . . . . . . . . . . . . . . . . .134
Chapter 11 MassPay API Operation . . . . . . . . . . . . . . . . . . 135
MassPay Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
MassPay Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
MassPay Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
MassPay Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
Chapter 12 Recurring Payments and Reference Transactions API
Operations137
CreateRecurringPaymentsProfile API Operation . . . . . . . . . . . . . . . . . . . . . .137
CreateRecurringPaymentsProfile Request Message . . . . . . . . . . . . . . . . . .137
CreateRecurringPaymentsProfile Response Message . . . . . . . . . . . . . . . . .145
GetRecurringPaymentsProfileDetails API Operation . . . . . . . . . . . . . . . . . . . .146
GetRecurringPaymentsProfileDetails Request Message . . . . . . . . . . . . . . . .146
GetRecurringPaymentsProfileDetails Response Message . . . . . . . . . . . . . . .146
ManageRecurringPaymentsProfileStatus API Operation . . . . . . . . . . . . . . . . . .154
ManageRecurringPaymentsProfileStatus Request Message . . . . . . . . . . . . . .154
ManageRecurringPaymentsProfileStatus Response Message . . . . . . . . . . . . .154
BillOutstandingAmount API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
BillOutstandingAmount Request Message . . . . . . . . . . . . . . . . . . . . . . .155
BillOutstandingAmount Response Message. . . . . . . . . . . . . . . . . . . . . . .155
UpdateRecurringPaymentsProfile API Operation . . . . . . . . . . . . . . . . . . . . . .156
UpdateRecurringPaymentsProfile Request Message . . . . . . . . . . . . . . . . . .156
UpdateRecurringPaymentsProfile Response Message . . . . . . . . . . . . . . . . .161
CreateBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . .161
CreateBillingAgreement Request Message . . . . . . . . . . . . . . . . . . . . . . .161
Name-Value Pair API Developer Guide August 2012 7
Contents
CreateBillingAgreement API Response Message . . . . . . . . . . . . . . . . . . . .162
SetCustomerBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . .162
SetCustomerBillingAgreement Request Message. . . . . . . . . . . . . . . . . . . .162
SetCustomerBillingAgreement Response Message . . . . . . . . . . . . . . . . . . .165
GetBillingAgreementCustomerDetails API Operation . . . . . . . . . . . . . . . . . . . .166
GetBillingAgreementCustomerDetails Request Message . . . . . . . . . . . . . . . .166
GetBillingAgreementCustomerDetails Response Message . . . . . . . . . . . . . . .166
BAUpdate API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
BAUpdate Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
BAUpdate Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
DoReferenceTransaction API Operation. . . . . . . . . . . . . . . . . . . . . . . . . . .171
DoReferenceTransaction Request Message . . . . . . . . . . . . . . . . . . . . . .171
DoReferenceTransaction Response Message . . . . . . . . . . . . . . . . . . . . .178
Chapter 13 RefundTransaction API Operation . . . . . . . . . . . . . 185
RefundTransaction Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
RefundTransaction Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .185
Merchant Store Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
RefundTransaction Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . .187
RefundTransaction Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .187
RefundInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
Chapter 14 TransactionSearch API Operation . . . . . . . . . . . . . 189
TransactionSearch Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
TransactionSearch Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .189
Payer Name Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
TransactionSearch Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . .192
TransactionSearch Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .192
Appendix A API Error Codes . . . . . . . . . . . . . . . . . . . . . . 193
General API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194
DirectPayment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
SetExpressCheckout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
GetExpressCheckoutDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . .223
DoExpressCheckoutPayment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . .224
Authorization and Capture API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
Contents
8August 2012 Name-Value Pair API Developer Guide
GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
Recurring Payments Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
SetCustomerBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
GetBillingAgreementCustomerDetails Errors . . . . . . . . . . . . . . . . . . . . . . . .253
CreateBillingAgreement Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253
UpdateBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
DoReferenceTransaction Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
AddressVerify API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262
ManagePendingTransactionStatus API Errors . . . . . . . . . . . . . . . . . . . . . . . .262
Appendix B Countries and Regions Supported by PayPal . . . . . . 263
Appendix C State and Province Codes . . . . . . . . . . . . . . . . . 271
Appendix D Currency Codes . . . . . . . . . . . . . . . . . . . . . . 275
Appendix E AVS and CVV2 Response Codes . . . . . . . . . . . . . 277
AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277
AVS Response Codes for Visa, MasterCard, Discover, and American Express . . . .277
AVS Response Codes for Maestro . . . . . . . . . . . . . . . . . . . . . . . . . . .278
CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279
CVV2 Response Codes for Visa, MasterCard, Discover, and American Express . . . .279
CVV2 Response Codes for Maestro. . . . . . . . . . . . . . . . . . . . . . . . . . .279
About Previous Versions of the API . . . . . . . . . . . . . . . . . . . 281
What’s New in Version 92.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
What’s New in Version 89.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
What’s New in Version 88.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
What’s New in Version 85.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
What’s New in Version 84.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
New Field in RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . .282
New RefundInfoType in RefundTransaction Response . . . . . . . . . . . . . . . . .282
New Field in DoReferenceTransactionResponseDetailsType . . . . . . . . . . . . .282
New Field in DoDirectPaymentResponse . . . . . . . . . . . . . . . . . . . . . . . .282
Name-Value Pair API Developer Guide August 2012 9
Contents
What’s New in Version 82.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283
New Field in DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . .283
New MerchantStoreDetailsType in DoCapture Request . . . . . . . . . . . . . . . . .283
New Fields in RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . .283
New MerchantStoreDetailsType in RefundTransaction Request . . . . . . . . . . . .284
What’s New in Version 80.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
New Fields in PaymentDetailsType in DoReferenceTransaction Request . . . . . . .285
What’s New in Version 74.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
New Behavior of DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . .285
New DoExpressCheckoutPayment Error Code . . . . . . . . . . . . . . . . . . . . .285
What’s New in Version 72.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286
New TaxIdDetailsType Structure in SetExpressCheckout Request . . . . . . . . . . .286
New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response . . . . . .286
What’s New in Version 69 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
New PaymentDetailsItemType Structure in CreateRecurringPaymentsProfile Request . .
287
Changes to PaymentDetailsItemType in DoReferenceTransaction Request . . . . . .288
What’s New in Version 66 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
Changes to PaymentDetailsType in SetExpressCheckout and
DoExpressCheckoutPayment Requests. . . . . . . . . . . . . . . . . . . . . . . . .289
Changes to PaymentDetailsItemTypein SetExpressCheckout and
DoExpressCheckoutPayment Requests . . . . . . . . . . . . . . . . . . . . . . . .289
Changes to PaymentDetailsItemType in GetExpressCheckoutDetails Response . . .291
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Contents
10 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 11
What’s New
What’s New in Version 93.0
Maintenance release. New 10486 error code added for redirects when the process declines the
transaction: The transaction couldn’t be completed. Please redirect your customer to PayPal.
What’s New in Version 93.0
12 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 13
Preface
About This Guide
The Name-Value Pair API Developer Guide describes the PayPal Name-Value Pair API.
Intended Audience
This guide is written for developers who are implementing solutions using the Name-Value
Pair API.
Where to Go for More Information
-Express Checkout Integration Guide
-Express Checkout Advanced Features Guide
-Merchant Setup and Administration Guide
Documentation Feedback
Help us improve this guide by sending feedback to:
documentationfeedback@paypal.com
Documentation Feedback
14 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 15
1PayPal Name-Value Pair API
Basics
The Name-Value Pair (NVP) API provides parameter-based association between request and
response fields of a message and their values. The request message is sent from your website
by the API, and a response message is returned by PayPal using a client-server model in which
your site is a client of the PayPal server.
NOTE:The PayFlow API also uses name-value pairs to provide parameter-based association
between request and response fields of a message and their values; however, the
PayFlow API is not the same as the NVP API; for more information about the
PayFlow API, see Gateway Developer Guide and Reference.
PayPal API Client-Server Architecture
The PayPal API uses a client-server model in which your website is a client of the PayPal
server.
A page on your website initiates an action on a PayPal API server by sending a request to the
server. The PayPal server responds with a confirmation that the requested action was taken or
indicates that an error occurred. The response might also contain additional information
related to the request. The following diagram shows the basic request-response mechanism.
For example, you might want to obtain the buyer’s shipping address from PayPal. You can
initiate a request specifying an API operation to obtain buyer details. The response from the
PayPal API server contains information about whether the request was successful. If the
operation succeeds, the response contains the requested information. In this case, the response
contains the buyer’s shipping address. If the operation fails, the response contains one or more
error messages.
Related information:
Creating an NVP Request
Responding to an NVP Response
PayPal Name-Value Pair API Basics
PayPal API Client-Server Architecture
1
16 August 2012 Name-Value Pair API Developer Guide
PayPal Name-Value Pair API Requests and Responses
To perform a PayPal NVP API operation, you send an NVP-formatted request to a PayPal
NVP server and interpret the response.
In the following diagram, your website generates a request. The request is executed on a
PayPal server and the response is returned to your site.
The request identifies:
-The name of the API operation, specified by METHOD=name, to be performed and its
version
NOTE:After the METHOD parameter, you can specify the parameters in any order.
-Credentials that identify the PayPal account making the request
-Request-specific information that controls the API operation to be performed
A PayPal API server performs the operation and returns a response. The response contains:
-An acknowledgement status that indicates whether the operation was a success or failure
and whether any warning messages were returned
-Information that can be used by PayPal to track execution of the API operation
-Response-specific information required to fulfill the request
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.
Multiple API Operations
Some of the features, such as Express Checkout, require you to call multiple API operations.
Typically, these features require you to:
Name-Value Pair API Developer Guide August 2012 17
PayPal Name-Value Pair API Basics
NVP Format 1
1. Invoke an API operation, such as SetExpressCheckout, that sets up the return URL to
which PayPal redirects your buyer’s browser after the buyer finishes on PayPal. Other
setup actions also can be performed by this API operation.
2. Invoke additional API operations after receiving the buyer’s permission on PayPal, for
example, GetExpressCheckoutDetails or DoExpressCheckoutPayment.
The following diagram shows the execution flow between your site and PayPal:
Token Usage
Typically, the API operation that sets up a redirection to PayPal returns a token. This token is
passed as a parameter in the redirect to PayPal. The token also might be required in related
API operations.
NVP Format
NVP is a way of specifying names and values in a string. NVP is the informal name for the
query in the URI specification. The NVP string is appended to the URL.
An NVP string conforms to the following guidelines:
-The name is separated from the value by an equal sign (=). For example:
FIRSTNAME=Robert
PayPal Name-Value Pair API Basics
Creating an NVP Request
1
18 August 2012 Name-Value Pair API Developer Guide
-Name-value pairs are separated by an ampersand (&). For example:
FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore
-The values for each value in an NVP string are URL-encoded.
Creating an NVP Request
The Name-Value Pair request format specifies the API operation to perform, credentials that
authorize PayPal to access your account, and fields containing additional information to be
used in the request.
Related information:
PayPal API Client-Server Architecture
Specifying the PayPal API Operation
For the NVP version of the PayPal API, you must specify the name of the PayPal API
operation to execute in each request along with the version of the API operation.
The following diagram shows the API operation part of an NVP request:
A method specifies the PayPal operation you want to execute, and each method is associated
with a version. Together, the method and version define the exact behavior of the API
operation. Typically, the behavior of an API operation does not change between versions;
however, you should carefully retest your code whenever you change a version.
To specify a method and version number:
1. Choose the PayPal API operation you want to use.
METHOD=operation
2. Choose the appropriate version.
In most cases, you should use the latest version of the API operation.
VERSION=version_number
Name-Value Pair API Developer Guide August 2012 19
PayPal Name-Value Pair API Basics
Creating an NVP Request 1
Specifying an API Credential Using Signatures
You must specify API credentials in each request to execute a PayPal API operation. You can
use either a signature or a certificate, but not both.
When you execute a PayPal API operation, you use credentials, such as a signature, to
authenticate that you are requesting the API operation. The following diagram shows the API
credentials part of an NVP request:
IMPORTANT:You must protect the values for USER, PWD, and SIGNATURE in your
implementation. Consider storing these values in a secure location other than
your web server document root and setting the file permissions so that only
the system user that executes your ecommerce application can access it.
To enable PayPal to authenticate your request:
1. Specify the API username associated with your account.
USER=API_username
2. Specify the password associated with the API user name.
PWD=API_password
3. If you are using an API signature and not an API certificate, specify the API signature
associated with the API username.
SIGNATURE=API_signature
4. Optionally, you can specify the email address on file with PayPal of the third-party
merchant on whose behalf you are calling the API operation.
SUBJECT=merchantEmailAddress
NOTE:Typically, a merchant grants third-party permissions to a shopping cart. The merchant
previously must have given you permission to execute the API operation.
Specifying Credentials Using cURL
The following example shows one way to specify a signature using cURL:
PayPal Name-Value Pair API Basics
Creating an NVP Request
1
20 August 2012 Name-Value Pair API Developer Guide
curl --insecure https://api-3t.sandbox.paypal.com/nvp -d ^
"METHOD=name^ &VERSION=XX.0^ &USER=API_username^ &PWD=API_password^
&SIGNATURE=API_signature^ &..."
NOTE:This example does not establish a secure connection and should not be used live on
paypal.com.
URL Encoding
All requests to execute PayPal API operations sent using HTTP must be URL-encoded. The
encoding ensures that you can transmit special characters, characters that are not allowed in a
URL, and characters that have special meaning in a URL, such as the equal sign and
ampersand.
The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a
PayPal API server. You must encode all data sent using the HTTP protocol because data that is
not encoded could be misinterpreted as part of the HTTP protocol instead of part of the
request. Most programming languages provide a way to encode strings in this way. You should
consistently URL-encode the complete API request; otherwise, you may find that
unanticipated data causes an error.
NOTE:An HTTP form is automatically URL-encoded by most browsers.
For example, consider the following NVP string:
NAME=Robert Moore&COMPANY=R. H. Moore & Associates
It is encoded as follows:
NAME=Robert+Moore&COMPANY=R.+H.+Moore+%26+Associates
Use the following methods to URL-encode or URL-decode your NVP strings:
Encoding and decoding methods for URLs
Language Method
ASP.NET Encode System.Web.HttpUtility.UrlEncode(buffer,
Encoding.Default)
Decode System.Web.HttpUtility.UrlDecode(buffer,
Encoding.Default)
Classic ASP Encode Server.URLEncode
Decode No built-in function. Several implementation examples are available on the
Internet.
Java Encode java.net.URLEncoder.encode
Decode java.net.URLDecoder.decode
Name-Value Pair API Developer Guide August 2012 21
PayPal Name-Value Pair API Basics
Executing NVP API Operations 1
Related information:
URL Decoding
List Syntax for Name-Value Pairs
The PayPal API uses a special syntax for NVP fields defined as lists.
The NVP interface to the PayPal API requires a unique name for each field. In the API, lists
are prefixed by L_. To identify an element within the list, use the offset from the beginning of
the list, starting with 0 as the first element. For example, L_DESC0 is the first line of a
description, L_DESC1, is the second line, and so on.
NOTE:Not all lists follow the L_ prefix convention; however, all lists start with 0 as the first
element.
Executing NVP API Operations
You execute a PayPal NVP API operation by submitting an HTTPS POST request to a PayPal
API server, or by using cURL or another mechanism to provide secure access between the
buyer’s browser and the PayPal API server. For example, you might implement a system in
which the buyer’s browser remains a client of your server and your server becomes a client of
the PayPal API server.
Specifying a PayPal Server
You execute a PayPal API operation by submitting the request to a PayPal API server.
To execute a PayPal NVP API operation, submit the request to one of the following end
points:
PHP Encode urlencode()
Decode urldecode()
ColdFusion Encode URLEncodedFormatstring [, charset]
Decode URLDecodeurlEncodedString[, charset])
Server end point Description
https://api-
3t.sandbox.paypal.com/nvp
Sandbox server for use with API signatures; use for testing your
API
Language Method
PayPal Name-Value Pair API Basics
Responding to an NVP Response
1
22 August 2012 Name-Value Pair API Developer Guide
NOTE:You must use different API credentials for each server end point. Typically, you obtain
API credentials when you test in the Sandbox and then obtain another set of
credentials for the production server. You must change each API request to use the
new credentials when you go live.
Logging API Operations
You should log basic information from the request and response messages of each PayPal API
operation you execute. You must log the Correlation ID from the response message, which
identifies the API operation to PayPal and which must be provided to Merchant Technical
Support if you need their assistance with a specific transaction.
All responses to PayPal API operations contain information that may be useful for debugging
purposes. In addition to logging the Correlation ID from the response message, you can log
other information, such as the transaction ID and timestamp, to enable you to review a
transaction on the PayPal website or through the API. You could implement a scheme that logs
the entire request and response in a “verbose” mode; however, you should never log the
password from a request.
Responding to an NVP Response
The Name-Value Pair response consists of the answer to the request as well as common fields
that identify the API operation and how it was executed.
The following diagram shows fields in the response to a PayPal NVP API operation:
Related information:
PayPal API Client-Server Architecture
https://api-3t.paypal.com/nvp PayPal “live” production server for use with API signatures
https://api.sandbox.paypal.com/nvp Sandbox server for use with API certificates; use for testing
your API
https://api.paypal.com/nvp PayPal “live” production server for use with API certificates
Server end point Description
Name-Value Pair API Developer Guide August 2012 23
PayPal Name-Value Pair API Basics
Responding to an NVP Response 1
Common Response Fields
The PayPal API always returns common fields in addition to fields that are specific to the
requested PayPal API operation.
A PayPal API response includes the following fields:
Error Responses
If the ACK value is not Success, API response fields may not be returned. An error response
has the following general format.
Format of an Error Response
Additional pass-through information may appear in the L_ERRORPARAMIDn and
L_ERRORPARAMVALUEn fields. Consider the following error response:
TIMESTAMP=2011%2d11%2d15T20%3a27%3a02Z&CORRELATIONID=5be53331d9700&ACK=Fail
ure&VERSION=78%2e0&BUILD=000000&L_ERRORCODE0=15005&L_SHORTMESSAGE0=Processo
r%20Decline&L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e&
L_SEVERITYCODE0=Error&L_ERRORPARAMID0=ProcessorResponse&L_ERRORPARAMVALUE0=
0051&AMT=10%2e40&CURRENCYCODE=USD&AVSCODE=X&CVV2MATCH=M
Field Description
ACK Acknowledgement status, which is one of the following values:
-Success indicates a successful operation.
-SuccessWithWarning indicates a successful operation; however, there are
messages returned in the response that you should examine.
-Failure indicates the operation failed; the response also contains one or more error
messages explaining the failure.
-FailureWithWarning indicates that the operation failed and that there are
messages returned in the response that you should examine.
CORRELATIONID Correlation ID, which uniquely identifies the transaction to PayPal.
TIMESTAMP The date and time that the requested API operation was performed.
VERSION The version of the API.
BUILD The sub-version of the API.
Response Fields on
Error
ACK=notSuccess&TIMESTAMP=date/timeOfResponse&
CORRELATIONID=debuggingToken&VERSION=VersionNo&
BUILD=buildNumber&L_ERRORCODE0=errorCode&
L_SHORTMESSAGE0=shortMessage&
L_LONGMESSAGE0=longMessage&
L_SEVERITYCODE0=severityCode
Multiple errors can be
returned. Each set of
errors has a different
numeric suffix, starting
with 0 and incremented
by one for each error.
PayPal Name-Value Pair API Basics
Responding to an NVP Response
1
24 August 2012 Name-Value Pair API Developer Guide
In this case, the parameter ID is ProcessorResponse, which indicates an error response by
a credit or debit card processor. The value contains the processor-specific error. These values
are not set by PayPal; rather, they are passed through from the source.
NOTE:PayPal only passes selected values in the L_ERRORPARAMIDn and
L_ERRORPARAMVALUEn fields.
URL Decoding
All responses to HTTP POST operations used by the PayPal NVP API must be decoded.
The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a
PayPal API server. You must decode all data returned using the HTTP protocol so that it can
be displayed properly. Most programming languages provide a way to decode strings.
Related information:
URL Encoding
Name-Value Pair API Developer Guide August 2012 25
2AddressVerify API Operation
The AddressVerify API operation confirms whether a postal address and postal code match
those of the specified PayPal account holder.
AddressVerify Request Message
Address Verify Request Fields
Field Description
METHOD (Required) Must be AddressVerify.
EMAIL (Required) Email address of a PayPal member to verify.
Character length and limitations: 255 single-byte characters maximum with the input
mask: ?@?.??
STREET (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 (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 API Operation
AddressVerify Response Message
2
26 August 2012 Name-Value Pair API Developer Guide
AddressVerify Response Message
Address Verify Response Fields
Field Description
CONFIRMATIONCODE Indicates whether the address is a confirmed address on file at PayPal. It is one of the
following values:
-None – The request value of the Email element does not match any email address
on file at PayPal.
-Confirmed – If the response value of the StreetMatch element is Matched,
the entire postal address is confirmed.
-Unconfirmed – PayPal responds that the postal address is unconfirmed.
NOTE:The values Confirmed and Unconfirmed both indicate that the member
email address passed verification.
STREETMATCH 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 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 Country code (ISO 3166) on file for the PayPal email address.
Character length and limitations: 2 single-byte characters
TOKEN 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
Name-Value Pair API Developer Guide August 2012 27
3Authorization and Capture API
Operation Reference
The Authorization and Capture API operations describe the PayPal API operations related to
delayed payment settlement:
DoCapture API Operation
Captures an authorized payment.
DoCapture Request Message
DoCapture Request Fields
Field Description
METHOD (Required) Must be DoCapture.
AUTHORIZATIONID (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
AMT (Required) Amount to capture.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
CURRENCYCODE (Optional) A 3-character currency code (default is USD).
COMPLETETYPE (Required) Indicates whether or not this is your last capture. It is one of the following
values:
-Complete – This is the last capture you intend to make.
-NotComplete – You intend to make additional captures.
NOTE:If Complete, any remaining amount of the original authorized transaction is
automatically voided and all remaining open authorizations are voided.
Authorization and Capture API Operation Reference
DoCapture API Operation
3
28 August 2012 Name-Value Pair API Developer Guide
INVNUM (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 (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
SOFTDESCRIPTOR (Optional) Per transaction description of the payment that is passed to the buyer’s
credit card statement.
If you provide a value in this field, the full descriptor displayed on the buyer’s
statement has the following format:
<PP * | PAYPAL *><Merchant descriptor as set in the Payment
Receiving Preferences><1 space><soft descriptor>
Character length and limitations: The soft descriptor can contain only the following
characters:
-Alphanumeric characters
-- (dash)
-* (asterisk)
-. (period)
- {space}
If you pass any other characters (such as “,”), PayPal returns an error code.
The soft descriptor does not include the phone number, which can be toggled between
your customer service number and PayPal’s Customer Service number.
The maximum length of the soft descriptor is 22 characters. Of this, the PayPal prefix
uses either 4 or 8 characters of the data format. Thus, the maximum length of the soft
descriptor information that you can pass in this field is:
22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment
Receiving Preferences> + 1)
For example, assume the following conditions:
-The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.
-The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
-The soft descriptor is passed in as JanesFlowerGifts LLC.
The resulting descriptor string on the credit card is:
PAYPAL *EBAY JanesFlow
MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
Name-Value Pair API Developer Guide August 2012 29
Authorization and Capture API Operation Reference
DoCapture API Operation 3
Merchant Store Details Fields
DoCapture Response Message
NOTE:If you use version 56.0 or later of the DoCaptue API, only the authorization ID,
transaction ID, transaction type, payment date, gross amount, and payment status are
guaranteed to be returned. If you need the values of other fields and they are not
returned, you can obtain their values later by calling GetTransactionDetails or
by using the reporting mechanism. Not applicable to point of sale transactions.
DoCapture Response Fields
Payment Information Fields
Field Description
STOREID 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 (Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
Field Description
AUTHORIZATIONID Authorization identification number you specified in the request.
Character length and limits: 19 single-byte characters maximum
MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
TRANSACTIONID Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters
Authorization and Capture API Operation Reference
DoCapture API Operation
3
30 August 2012 Name-Value Pair API Developer Guide
PARENTTRANSACTIONID Parent or related transaction identification number. This field is populated for the
following transaction types:
-Reversal. Capture of an authorized transaction.
-Reversal. Reauthorization of a transaction.
-Capture of an order. The value of ParentTransactionID is the original
OrderID.
-Authorization of an order. The value of ParentTransactionID is the original
OrderID.
-Capture of an order authorization.
-Void of an order. The value of ParentTransactionID is the original OrderID.
Character length and limitations: 16 digits
Only authorization of an order and capture of an order authorization apply to point-
of-sale transactions.
RECEIPTID Receipt identification number.
Character length and limitations: 16 digits
Empty for point-of-sale transactions.
TRANSACTIONTYPE The type of transaction. It is one of the following values:
-cart
-express-checkout
Character length and limitations:15 single-byte characters
PAYMENTTYPE 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
ORDERTIME Time/date stamp of payment. For example: 2006-08-15T17:23:15Z
AMT 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.
FEEAMT 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.
Field Description
Name-Value Pair API Developer Guide August 2012 31
Authorization and Capture API Operation Reference
DoCapture API Operation 3
SETTLEAMT 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.
TAXAMT 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 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
PAYMENTSTATUS Status of the payment. It is one of the following values:
NOTE:In a successful DoCapture response for a point-of-sale authorization, the only
value value is Completed.
-None – No status
-Canceled-Reversal – This means a reversal has been canceled. For example,
you won a dispute with the customer, and the funds for the transaction that was
reversed have been returned to you.
-Completed – The payment has been completed, and the funds have been added
successfully to your account balance. This is the only value status for point-of-
sale transactions.
-Denied – You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the PendingReason
element.
-Expired – The authorization period for this payment has been reached.
-Failed – The payment has failed. This happens only if the payment was made
from your customer’s bank account.
-Pending – The payment is pending. See the PendingReason field for more
information.
-Refunded – You refunded the payment.
-Reversed – A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer. The reason for the reversal is specified in the ReasonCode element.
-Processed – A payment has been accepted.
-Voided – An authorization for this transaction has been voided.
Field Description
Authorization and Capture API Operation Reference
DoAuthorization API Operation
3
32 August 2012 Name-Value Pair API Developer Guide
DoAuthorization API Operation
Authorize a payment.
DoAuthorization Request Message
DoAuthorization Request Fields
PENDINGREASON NOTE:PendingReason is returned in the response only if PaymentStatus is
Pending. This field does not apply to capturing point-of-sale authorizations,
which do not create pending payments.
Reason the payment is pending. It is one of the following values:
-none: – No pending reason.
-address – The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set such
that you want to manually accept or deny each of these payments. To change your
preference, go to the Preferences section of your Profile.
-echeck – The payment is pending because it was made by an eCheck that has not
yet cleared.
-intl –The payment is pending because you hold a non-U.S. account and do not
have a withdrawal mechanism. You must manually accept or deny this payment
from your Account Overview.
-multi-currency – You do not have a balance in the currency sent, and you do
not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this payment.
-verify – The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
-other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal Customer Service.
Field Description
METHOD (Required) Must be DoAuthorization.
TRANSACTIONID (Required) Value of the order’s transaction identification number returned by PayPal.
Character length and limitations: 19 single-byte characters
AMT (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 (,).
Field Description
Name-Value Pair API Developer Guide August 2012 33
Authorization and Capture API Operation Reference
DoAuthorization API Operation 3
DoAuthorization Response Message
DoAuthorization Response Fields
TRANSACTIONENTITY (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.
CURRENCYCODE (Optional) A 3-character currency code.
MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
TRANSACTIONID Authorization identification number.
AMT 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 (,).
MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
Authorization and Capture API Operation Reference
DoAuthorization API Operation
3
34 August 2012 Name-Value Pair API Developer Guide
AuthorizationInfo Fields
Field Description
PAYMENTSTATUS 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.
Name-Value Pair API Developer Guide August 2012 35
Authorization and Capture API Operation Reference
DoAuthorization API Operation 3
PENDINGREASON Reason the payment is pending. It is one of the following values:
-none – No pending reason.
-address – The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set
such that you want to manually accept or deny each of these payments. To
change your preference, go to the Preferences section of your Profile.
-authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
-echeck – The payment is pending because it was made by an eCheck that has
not yet cleared.
-intl – The payment is pending because you hold a non-U.S. account and do
not have a withdrawal mechanism. You must manually accept or deny this
payment from your Account Overview.
-multi-currency – You do not have a balance in the currency sent, and you
do not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this
payment.
-order – The payment is pending because it is part of an order that has been
authorized but not settled.
-paymentreview – The payment is pending while it is being reviewed by
PayPal for risk.
-unilateral – The payment is pending because it was made to an email
address that is not yet registered or confirmed.
-verify – The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
-other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal Customer Service.
NOTE:PendingReason is returned in the response only if PaymentStatus is
Pending.
PROTECTIONELIGIBILITY Prior to version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for
Unauthorized Payment and Item Not Received.
-PartiallyEligible – Merchant is protected by PayPal's Seller Protection
Policy for Item Not Received.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
Field Description
Authorization and Capture API Operation Reference
DoReauthorization API Operation
3
36 August 2012 Name-Value Pair API Developer Guide
DoReauthorization API Operation
DoReauthorization Request Message
DoReauthorization Request Fields
PROTECTIONELIGIBILITY
TYPE
Since version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for
both Unauthorized Payment and Item Not Received.
-ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received.
-UnauthorizedPaymentEligible – Merchant is protected by PayPal's
Seller Protection Policy for Unauthorized Payment.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
This field is available since version 64.4.
Field Description
METHOD (Required) Must be DoReauthorization.
AUTHORIZATIONID (Required) Value of a previously authorized transaction identification number
returned by PayPal.
Character length and limitations: 19 single-byte characters
AMT (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 (,).
CURRENCYCODE (Optional)
3-character, ISO 4217 currency code. Default value is USD.
Character length and limitations: 3 single-byte characters
Field Description
Name-Value Pair API Developer Guide August 2012 37
Authorization and Capture API Operation Reference
DoReauthorization API Operation 3
DoReauthorization Response Message
DoReauthorization Response Fields
Authorization Information Fields
Field Description
AUTHORIZATIONID New authorization identification number.
Character length and limits:19 single-byte characters
Field Description
PAYMENTSTATUS 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.
Authorization and Capture API Operation Reference
DoReauthorization API Operation
3
38 August 2012 Name-Value Pair API Developer Guide
PENDINGREASON Reason the payment is pending. It is one of the following values:
-none – No pending reason.
-address – The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set
such that you want to manually accept or deny each of these payments. To
change your preference, go to the Preferences section of your Profile.
-authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
-echeck – The payment is pending because it was made by an eCheck that has
not yet cleared.
-intl – The payment is pending because you hold a non-U.S. account and do
not have a withdrawal mechanism. You must manually accept or deny this
payment from your Account Overview.
-multi-currency – You do not have a balance in the currency sent, and you
do not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this
payment.
-order – The payment is pending because it is part of an order that has been
authorized but not settled.
-paymentreview – The payment is pending while it is being reviewed by
PayPal for risk.
-unilateral – The payment is pending because it was made to an email
address that is not yet registered or confirmed.
-verify – The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
-other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal Customer Service.
NOTE:PendingReason is returned in the response only if PaymentStatus is
Pending.
PROTECTIONELIGIBILITY Prior to version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for
Unauthorized Payment and Item Not Received.
-PartiallyEligible – Merchant is protected by PayPal's Seller Protection
Policy for Item Not Received.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
Field Description
Name-Value Pair API Developer Guide August 2012 39
Authorization and Capture API Operation Reference
DoVoid API Operation 3
DoVoid API Operation
Void an order or an authorization.
DoVoid Request Message
DoVoid Request Fields
DoVoid Response Message
DoVoid Response Fields
PROTECTIONELIGIBILITY
TYPE
Since version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for
both Unauthorized Payment and Item Not Received.
-ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received.
-UnauthorizedPaymentEligible – Merchant is protected by PayPal's
Seller Protection Policy for Unauthorized Payment.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
This field is available since version 64.4.
Field Description
METHOD (Required) Must be DoVoid.
AUTHORIZATIONID (Required) Original authorization ID specifying the authorization to void or, to void
an order, the order ID.
IMPORTANT:If you are voiding a transaction that has been reauthorized, use the ID
from the original authorization, and not the reauthorization.
Character length and limitations: 19 single-byte characters
NOTE (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
Field Description
AUTHORIZATIONID Authorization identification number you specified in the request.
Character length and limitations: 19 single-byte characters
Field Description
Authorization and Capture API Operation Reference
DoVoid API Operation
3
40 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 41
4DoDirectPayment API Operation
The DoDirectPayment API Operation enables you to process a credit card payment.
DoDirectPayment Request Message
DoDirectPayment Request Fields
Field Description
METHOD (Required) Must be DoDirectPayment.
PAYMENTACTION (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
IPADDRESS (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
RETURNFMFDETAILS (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.
DoDirectPayment API Operation
DoDirectPayment Request Message
4
42 August 2012 Name-Value Pair API Developer Guide
Credit Card Details Fields
Payer Information Fields
Field Description
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 CURRENCYCODE to GBP. In
addition, you must specify either STARTDATE or ISSUENUMBER.
Character length and limitations: Up to 10 single-byte alphabetic characters
ACCT (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.
EXPDATE Credit card expiration date. This field is required if you are using recurring payments
with direct payments.
Character length and limitations: 6 single-byte alphanumeric characters, including
leading zero, in the format MMYYYY
CVV2 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.
STARTDATE (Optional) Month and year that Maestro card was issued.
Character length and limitations: Must be 6 digits, including leading zero, in the
format MMYYYY
ISSUENUMBER (Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum
Field Description
EMAIL (Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters
FIRSTNAME (Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters
Name-Value Pair API Developer Guide August 2012 43
DoDirectPayment API Operation
DoDirectPayment Request Message 4
Address Fields
Payment Details Fields
LASTNAME (Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Field Description
STREET (Required) First street address.
Character length and limitations: 100 single-byte characters
STREET2 (Optional) Second street address.
Character length and limitations: 100 single-byte characters
CITY (Required) Name of city.
Character length and limitations: 40 single-byte characters
STATE (Required) State or province.
Character length and limitations: 40 single-byte characters
COUNTRYCODE (Required) Country code.
Character length and limitationst: 2 single-byte characters
ZIP (Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM (Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
AMT (Required) The total cost of the transaction to the buyer. If shipping cost and tax
charges are known, include them in this value. If not, this value should be the current
subtotal of the order. If the transaction includes one or more one-time purchases, this
field must be equal to the sum of the purchases. This field must be set to a value
greater than 0.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
CURRENCYCODE (Optional) A 3-character currency code (default is USD).
Field Description
DoDirectPayment API Operation
DoDirectPayment Request Message
4
44 August 2012 Name-Value Pair API Developer Guide
ITEMAMT (Optional) Sum of cost of all items in this order.
NOTE:ITEMAMT is required if you specify L_AMTn.
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 (,).
SHIPPINGAMT (Optional) Total shipping costs for this order.
NOTE:If you specify a value for SHIPPINGAMT, you must also specify a value for
ITEMAMT.
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 (,).
INSURANCEAMT (Optional) Total shipping insurance costs for this order. The value must be a non-
negative currency amount or null if you offer insurance options.
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 (,).
SHIPDISCAMT (Optional) Shipping discount for this order, specified as a negative number.
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 (,).
HANDLINGAMT (Optional) Total handling costs for this order.
NOTE:If you specify a value for HANDLINGAMT, you must also specify a value for
ITEMAMT.
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 (,).
TAXAMT (Optional) Sum of tax for all items in this order.
NOTE:TAXAMT is required if you specify L_TAXAMTn
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
Name-Value Pair API Developer Guide August 2012 45
DoDirectPayment API Operation
DoDirectPayment Request Message 4
DESC (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 (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
INVNUM (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 (Optional) An identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
NOTIFYURL (Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL from
your Merchant Profile is used, if one exists.
IMPORTANT:The notify URL applies only to DoExpressCheckoutPayment.
This value is ignored when set in SetExpressCheckout or
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
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.
Field Description
DoDirectPayment API Operation
DoDirectPayment Request Message
4
46 August 2012 Name-Value Pair API Developer Guide
Payment Details Item Fields
Ebay Item Payment Details Item Fields
Field Description
L_NAMEn(Optional) Item name. These parameters must be ordered sequentially beginning with
0 (for example L_NAME0, L_NAME1).
Character length and limitations: 127 single-byte characters
L_DESCn(Optional) Item description.
Character length and limitations: 127 single-byte characters
L_AMTn(Optional) Cost of item. These parameters must be ordered sequentially beginning
with 0 (for example L_AMT0, L_AMT1).
NOTE:If you specify a value for L_AMTn, you must specify a value for ITEMAMT.
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 (,).
L_NUMBERn(Optional) Item number. These parameters must be ordered sequentially beginning
with 0 (for example L_NUMBER0, L_NUMBER1).
Character length and limitations: 127 single-byte characters
L_QTYn(Optional) Item quantity. These parameters must be ordered sequentially beginning
with 0 (for example L_QTY0, L_QTY1).
Character length and limitations: Any positive integer
L_TAXAMTn(Optional) Item sales tax. These parameters must be ordered sequentially beginning
with 0 (for example L_TAXAMT0, L_TAXAMT1).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
L_EBAYITEMNUMBERn(Optional) Auction item number. These parameters must be ordered sequentially
beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1).
Character length: 765 single-byte characters
L_EBAYITEMAUCTIONTX
NIDn
(Optional) Auction transaction identification number. These parameters must be
ordered sequentially beginning with 0 (for example L_EBAYITEMAUCTIONTXNID0,
L_EBAYITEMAUCTIONTXNID1).
Character length: 255 single-byte characters
Name-Value Pair API Developer Guide August 2012 47
DoDirectPayment API Operation
DoDirectPayment Request Message 4
Ship To Address Fields
3D Secure Request Fields (U.K. Merchants Only)
L_EBAYITEMORDERIDn(Optional) Auction order identification number. These parameters must be ordered
sequentially beginning with 0 (for example L_EBAYITEMORDERID0,
L_EBAYITEMORDERID1).
Character length: 64 single-byte characters
Field Description
SHIPTONAME Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
SHIPTOSTREET First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 (Optional) Second street address.
Character length and limitations: 100 single-byte characters
SHIPTOCITY Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOZIP 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
SHIPTOCOUNTRY Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
SHIPTOPHONENUM (Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
AUTHSTATUS3DS (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 (Optional) A value returned by the Cardinal Centinel. Set this field to the
Enrolled value returned by cmpi_lookup.
Field Description
DoDirectPayment API Operation
DoDirectPayment Response Message
4
48 August 2012 Name-Value Pair API Developer Guide
DoDirectPayment Response Message
DoDirectPayment Response Fields
CAVV (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 (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 (Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set this field to the Xid value returned by
cmpi_authenticate. Otherwise, set this field to blank.
Field Description
TRANSACTIONID Unique transaction ID of the payment.
NOTE:If the PaymentAction of the request was Authorization, the value of
TransactionID is your AuthorizationID for use with the Authorization and
Capture APIs.
Character length and limitations: 19 single-byte characters
AMT This value is the amount of the payment as specified by you on
DoDirectPaymentRequest for reference transactions with direct payments.
AVSCODE Address Verification System response code.
Character length and limitations: 1 single-byte alphanumeric character
CVV2MATCH Result of the CVV2 check by PayPal.
Field Description
Name-Value Pair API Developer Guide August 2012 49
DoDirectPayment API Operation
DoDirectPayment Response Message 4
Related information:
AVS Response Codes
AVS Response Codes for Visa, MasterCard, Discover, and American Express
AVS Response Codes for Maestro
L_FMFfilterIDn Filter ID, including the filter type (PENDING, REPORT, or DENY), the filter ID, and
the entry number, n, starting from 0. Filter ID 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
L_FMFfilterNAMEnFilter name, including the filter type, (PENDING, REPORT, or DENY), the filter NAME,
and the entry number, n, starting from 0.
PAYMENTADVICECODE Response code from the processor when a recurrng transaction is declined. For details
on the codes, see https://merchant.paypal.com/us/cgi-bin/?&cmd=_render-
content&content_ID=merchant/cc_compliance_error_codes
Field Description
DoDirectPayment API Operation
DoDirectPayment Response Message
4
50 August 2012 Name-Value Pair API Developer Guide
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
Name-Value Pair API Developer Guide August 2012 51
5DoNonReferencedCredit API
Operation
The DoNonReferencedCredit API issues a credit to a card not referenced by the original
transaction.
DoNonReferencedCredit Request Message
DoNonReferencedCredit Request Fields
Field Description
METHOD (Required) Must be DoNonReferencedCredit.
AMT (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 (,).
NETAMT (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 (,).
TAXAMT (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 (,).
SHIPPINGAMT (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.
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message
5
52 August 2012 Name-Value Pair API Developer Guide
Credit Card Details Type Fields
NOTE (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).
CURRENCYCODE (Required) Currency code (default is USD).
NOTE: The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.
Field Description
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 CURRENCYCODE to GBP. In
addition, you must specify either STARTDATE or ISSUENUMBER.
Character length and limitations: Up to 10 single-byte alphabetic characters
ACCT (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.
EXPDATE Credit card expiration date. This field is required if you are using recurring payments
with direct payments.
Character length and limitations: 6 single-byte alphanumeric characters, including
leading zero, in the format MMYYYY
CVV2 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.
STARTDATE (Optional) Month and year that Maestro card was issued.
Character length and limitations: Must be 6 digits, including leading zero, in the
format MMYYYY
ISSUENUMBER (Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum
Field Description
Name-Value Pair API Developer Guide August 2012 53
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message 5
Payer Name Type Fields
Payer Information Fields
Address Fields
Field Description
SALUTATION (Optional) Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FIRSTNAME (Optional) Buyer’s first name.
Character length and limitations: 25 single-byte characters
MIDDLENAME (Optional) Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LASTNAME (Optional) Buyer’s last name.
Character length and limitations: 25 single-byte characters
SUFFIX (Optional) Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
EMAIL (Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters
FIRSTNAME (Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters
LASTNAME (Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Field Description
STREET (Required) First street address.
Character length and limitations: 100 single-byte characters
STREET2 (Optional) Second street address.
Character length and limitations: 100 single-byte characters
CITY (Required) Name of city.
Character length and limitations: 40 single-byte characters
STATE (Required) State or province.
Character length and limitations: 40 single-byte characters
DoNonReferencedCredit API Operation
DoNonReferencedCredit Response Message
5
54 August 2012 Name-Value Pair API Developer Guide
DoNonReferencedCredit Response Message
DoNonReferencedCredit Response Fields
COUNTRYCODE (Required) Country code.
Character length and limitationst: 2 single-byte characters
ZIP (Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM (Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
TRANSACTIONID Unique identifier of a transaction.
Character length and limitations: 17 single-byte alphanumeric characters.
CURRENCYCODE Currency code.
NOTE: The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.
Field Description
Name-Value Pair API Developer Guide August 2012 55
6ExpressCheckout API Operations
Express Checkout API operations include SetExpressCheckout,
GetExpressCheckoutDetails, and DoExpressCheckoutPayment.
Callback API Operation
Updates the PayPal Review page with shipping options, insurance, and tax information.
Callback API Request Message
Callback Request Fields
Field Description
METHOD (Required) Must be Callback.
TOKEN (Optional) A timestamped token, the value of which was returned by
SetExpressCheckout response.
Character length and limitations: 20 single-byte characters
CURRENCYCODE (Required) The three-character currency code for the transaction from the Express
Checkout API. Default: USD
ExpressCheckout API Operations
Callback API Operation
6
56 August 2012 Name-Value Pair API Developer Guide
LOCALECODE (Optional) Locale of pages displayed by PayPal during Express Checkout.
Character length and limitations: Any two-character country code.
The following two-character country codes are supported by PayPal:
-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 will default to US.
L_NAMEn Item name from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_NAME0, L_NAME1).
L_NUMBERn Item number from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_NUMBER0, L_NUMBER1).
Field Description
Name-Value Pair API Developer Guide August 2012 57
ExpressCheckout API Operations
Callback API Operation 6
L_DESCn Item description from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_DESC0, L_DESC1).
L_AMTn Item unit price from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_AMT0, L_AMT1).
L_QTYn Item unit quantity from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_QTY0, L_QTY1).
L_ITEMWEIGHTVALUEn
L_ITEMWEIGHTUNITn
The weight of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
These parameters must be ordered sequentially beginning with 0 (for example,
L_ITEMWEIGHTVALUE0, L_ITEMWEIGHTVALUE1).
L_ITEMHEIGHTVALUEn
L_ITEMHEIGHTUNITn
The height of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
These parameters must be ordered sequentially beginning with 0 (for example,
L_ITEMHEIGHTVALUE0, ITEMHEIGHTVALUE1).
L_ITEMWIDTHVALUEn
L_ITEMWIDTHUNITn
The width of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query..
These parameters must be ordered sequentially beginning with 0 (for example,
L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).
L_ITEMLENGTHVALUEn
L_ITEMLENGTHUNITn
The length of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
These parameters must be ordered sequentially beginning with 0 (for example,
ITEMLENGTHVALUE0, ITEMLENGTHVALUE1).
SHIPTOSTREET First street address. Required if using a shipping address.
Character length and limitations: 300 single-byte characters.
SHIPTOSTREET2 Second street address.
Character length and limitations: 300 single-byte characters.
SHIPTOCITY Name of city. Required if using a shipping address.
Character length and limitations: 40 single-byte characters.
SHIPTOSTATE State or province. Required if using a shipping address.
Character length and limitations: 40 single-byte characters.
SHIPTOZIP U.S. ZIP code or other country-specific postal code. Required if using a U.S. shipping
address; may be required for other countries.
Character length and limitations: 20 single-byte characters.
SHIPTOCOUNTRY Country code. Required if using a shipping address.
Character limit: 2 single-byte characters.
Field Description
ExpressCheckout API Operations
Callback API Operation
6
58 August 2012 Name-Value Pair API Developer Guide
Callback Response Message
Callback Response Fields
Field Description
METHOD (Required) The method sent to the PayPal server. The value is always
CallbackResponse.
CURRENCYCODE (Required) The three-character currency code for the transaction from the Express
Checkout API.
OFFERINSURANCEOPTIO
N
(Optional) Indicates whether or not PayPal should display insurance in a drop-down
list on the Review page. When the value is true, PayPal displays the drop-down
with the associated amount and the string ‘Yes.’
L_SHIPPINGOPTIONNAM
En
(Required) Is the internal/system name of a shipping option, such as Air, Ground, or
Expedited.
These parameters must be ordered sequentially beginning with 0 (for example,
L_SHIPPINGOPTIONNAME0, L_SHIPPINGOPTIONNAME1).
Character length and limitations: 50 characters
L_SHIPPINGOPTIONLAB
ELn
(Required) The label for the shipping option as displayed to the buyer. Examples: Air:
Next Day, Expedited: 3-5 days, Ground: 5-7 days. These labels can be localized
based on the buyer’s locale, which is a part of the callback request.
These parameters must be ordered sequentially beginning with 0 (for example,
L_SHIPPINGALABEL0, L_SHIPPINGLABEL1).
Character length and limitations: 50 characters
L_SHIPPINGOPTIONAMO
UNTn
(Required) Is the amount for this shipping option.
These parameters must be ordered sequentially beginning with 0 (for example,
L_SHIPPINGAMOUNT0, L_SHIPPINGAMOUNT1).
NOTE: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.
L_SHIPPINGOPTIONISD
EFAULT
(Required) The option that is selected by default for the buyer and is also reflected in
the “default” total.
L_TAXAMTn(Optional) New tax amount based on this shipping option and the shipping address.
NOTE: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.
Name-Value Pair API Developer Guide August 2012 59
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
SetExpressCheckout API Operation
The SetExpressCheckout API operation initiates an Express Checkout transaction.
SetExpressCheckout Request Message
SetExpressCheckout Request Fields
L_INSURANCEAMOUNTn(Optional) New insurance amount based on this shipping option and the shipping
address.
NOTE: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.
OFFERINSURANCEOPTIO
N
(Optional) Indicates whether or not PayPal should display insurance in a drop-down
list on the Review page. When the value is true, PayPal displays the drop-down
with the associated amount and the string ‘Yes.’
NO_SHIPPING_OPTION_
DETAILS
(Optional) If you do not ship to the buyer’s shipping address, set this field to 1. The
value of CALLBACKVERSION in SetExpressCheckout request must be 61.0 or
greater, similar to the following:
CALLBACKVERSION=<61.0 or greater>
Character length and limitations: string
Field Description
METHOD (Required) Must be SetExpressCheckout.
AMT (deprecated)(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.
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 (,).
AMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_AMT instead.
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
60 August 2012 Name-Value Pair API Developer Guide
MAXAMT (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.
RETURNURL (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 (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
CALLBACK (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 (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
REQCONFIRMSHIPPING 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
Field Description
Name-Value Pair API Developer Guide August 2012 61
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
NOSHIPPING 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
ALLOWNOTE (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.
ADDROVERRIDE (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
CALLBACKVERSION Version of the callback API. This field is required when implementing the Instant
Update Callback API. It must be set to 61.0 or a later version.
This field is available since version 61.0.
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
62 August 2012 Name-Value Pair API Developer Guide
LOCALECODE (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 (Optional) Name of the Custom Payment Page Style for payment pages associated
with this button or link. It corresponds to the HTML variable page_style for
customizing payment pages. It is the same name as the Page Style Name you chose to
add or edit the page style in your PayPal Account profile.
Character length and limitations: 30 single-byte alphabetic characters
Field Description
Name-Value Pair API Developer Guide August 2012 63
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
HDRIMG (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
HDRBORDERCOLOR (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
HDRBACKCOLOR (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
PAYFLOWCOLOR (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)
(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 PAYMENTREQUEST_0_PAYMENTACTION instead.
EMAIL (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
SOLUTIONTYPE (Optional) Type of checkout flow. It is one of the following values:
-Sole – Buyer does not need to create a PayPal account to check out. This is
referred to as PayPal Account Optional.
-Mark – Buyer must have a PayPal account to check out.
NOTE:You can pass Mark to selectively override the PayPal Account Optional
setting if PayPal Account Optional is turned on in your merchant account.
Passing Sole has no effect if PayPal Account Optional is turned off in your
account
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
64 August 2012 Name-Value Pair API Developer Guide
LANDINGPAGE (Optional) Type of PayPal page to display. It is one of the following values:
-Billing – Non-PayPal account
-Login – PayPal account login
CHANNELTYPE (Optional) Type of channel. It is one of the following values:
-Merchant – Non-auction seller
-eBayItem – eBay auction
GIROPAYSUCCESSURL (Optional) The URL on the merchant site to redirect to after a successful giropay
payment.
NOTE:Use this field only if you are using giropay or bank transfer payment methods
in Germany.
GIROPAYCANCELURL (Optional) The URL on the merchant site to redirect to after a successful giropay
payment.
NOTE:Use this field only if you are using giropay or bank transfer payment methods
in Germany.
BANKTXNPENDINGURL (Optional) The URL on the merchant site to transfer to after a bank transfer payment.
NOTE:Use this field only if you are using giropay or bank transfer payment methods
in Germany.
BRANDNAME (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
CUSTOMERSERVICENUMB
ER
(Optional) Merchant Customer Service number displayed on the PayPal pages.
Character length and limitations: 16 single-byte characters
GIFTMESSAGEENABLE (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 (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 (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 (Optional) Label for the gift wrap option such as “Box with ribbon”.
Character length and limitations: 25 single-byte characters
Field Description
Name-Value Pair API Developer Guide August 2012 65
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
GIFTWRAPAMOUNT (Optional) Amount to be charged to the buyer for gift wrapping..
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 (,).
BUYEREMAILOPTINENAB
LE
(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 (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 (Optional) Enables survey functionality. It is one of the following values:
-0 – Disables survey functionality.
-1 – Enables survey functionality.
L_SURVEYCHOICEn (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 (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 (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.
PAYMENTREQUEST_n_PA
YMENTREASON
Indicates the type of transaction. It is one of the following values:
-None – Transaction is not identified as a particular type.
-Refund – Identifies the transaction as a refund.
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
66 August 2012 Name-Value Pair API Developer Guide
AddressType Fields
Field Description
PAYMENTREQUEST_n_SHIPTONAM
E
SHIPTONAME (deprecated)
Person’s name associated with this shipping address. It is required if using a
shipping address. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
Character length and limitations: 32 single-byte characters
SHIPTONAME is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTONAME instead.
PAYMENTREQUEST_n_SHIPTOSTR
EET
SHIPTOSTREET (deprecated)
First street address. It is required if using a shipping address. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET instead.
PAYMENTREQUEST_n_SHIPTOSTR
EET2
SHIPTOSTREET2 (deprecated)
(Optional) Second street address. You can specify up to 10 payments, where
n is a digit between 0 and 9, inclusive.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET2 instead.
PAYMENTREQUEST_n_SHIPTOCIT
Y
SHIPTOCITY (deprecated)
Name of city. It is required if using a shipping address. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 40 single-byte characters
SHIPTOCITY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCITY instead.
PAYMENTREQUEST_n_SHIPTOSTA
TE
SHIPTOSTATE (deprecated)
State or province. It is required if using a shipping address. You can specify
up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTATE instead.
PAYMENTREQUEST_n_SHIPTOZIP
SHIPTOZIP (deprecated)
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. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 20 single-byte characters
SHIPTOZIP is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOZIP instead.
PAYMENTREQUEST_n_SHIPTOCOU
NTRYCODE
SHIPTOCOUNTRY (deprecated)
Country code. It is required if using a shipping address. You can specify up
to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 2 single-byte characters
SHIPTOCOUNTRY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE instead.
Name-Value Pair API Developer Guide August 2012 67
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
Payment Details Type 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.
PAYMENTREQUEST_n_SHIPTOPHO
NENUM
SHIPTOPHONENUM (deprecated)
(Optional) Phone number. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive.
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOPHONENUM instead.
Field Description
PAYMENTREQUEST_n_AMT
AMT (deprecated)
(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. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
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 (,).
AMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_AMT instead.
PAYMENTREQUEST_n_CUR
RENCYCODE
CURRENCYCODE
(deprecated)
(Optional) A 3-character currency code (default is USD). You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
CURRENCYCODE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_CURRENCYCODE instead.
PAYMENTREQUEST_n_ITE
MAMT
ITEMAMT (deprecated)
Sum of cost of all items in this order. For digital goods, this field is required. You
can specify up to 10 payments, where n is a digit between 0 and 9, inclusive; except
for digital goods, which supports single payments only.
NOTE:PAYMENTREQUEST_n_ITEMAMT is required if you specify
L_PAYMENTREQUEST_n_AMTm.
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 (,).
ITEMAMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_ITEMAMT
instead.
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
68 August 2012 Name-Value Pair API Developer Guide
PAYMENTREQUEST_n_SHI
PPINGAMT
SHIPPINGAMT (deprecated)
(Optional) Total shipping costs for this order. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive.
NOTE:If you specify a value for PAYMENTREQUEST_n_SHIPPINGAMT, you must
also specify a value for PAYMENTREQUEST_n_ITEMAMT.
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 (,).
SHIPPINGAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGAMT instead.
PAYMENTREQUEST_n_INS
URANCEAMT
INSURANCEAMT
(deprecated)
(Optional) Total shipping insurance costs for this order. The value must be a non-
negative currency amount or null if insurance options are offered. 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 (,).
INSURANCEAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_INSURANCEAMT instead.
PAYMENTREQUEST_n_SHI
PDISCAMT
SHIPPINGDISCAMT
(deprecated)
(Optional) Shipping discount for this order, specified as a negative number. 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 (,).
SHIPPINGDISCAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGDISCAMT instead.
PAYMENTREQUEST_n_INS
URANCEOPTIONOFFERED
INSURANCEOPTIONOFFER
ED (deprecated)
(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal Review page. You can specify up to 10 payments, where n is
a digit between 0 and 9, inclusive. 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.’
INSURANCEOPTIONOFFERED is deprecated since version 63.0. Use
PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED instead.
Field Description
Name-Value Pair API Developer Guide August 2012 69
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
PAYMENTREQUEST_n_HAN
DLINGAMT
HANDLINGAMT (deprecated)
(Optional) Total handling costs for this order. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive.
NOTE:If you specify a value for PAYMENTREQUEST_n_HANDLINGAMT, you must
also specify a value for PAYMENTREQUEST_n_ITEMAMT.
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 (,).
HANDLINGAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_HANDLINGAMT instead.
PAYMENTREQUEST_n_TAX
AMT
TAXAMT (deprecated)
(Optional) Sum of tax for all items in this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
NOTE:PAYMENTREQUEST_n_TAXAMT is required if you specify
L_PAYMENTREQUEST_n_TAXAMTm
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 (,).
TAXAMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_TAXAMT
instead.
PAYMENTREQUEST_n_DES
C
DESC (deprecated)
(Optional) Description of items the buyer is purchasing. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
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
DESC is deprecated since version 63.0. Use PAYMENTREQUEST_0_DESC instead.
PAYMENTREQUEST_n_CUS
TOM
CUSTOM (deprecated)
(Optional) A free-form field for your own use. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive.
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
CUSTOM is deprecated since version 63.0. Use PAYMENTREQUEST_0_CUSTOM
instead.
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
70 August 2012 Name-Value Pair API Developer Guide
PAYMENTREQUEST_n_INV
NUM
INVNUM (deprecated)
(Optional) Your own invoice or tracking number.You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
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
INVNUM is deprecated since version 63.0. Use PAYMENTREQUEST_0_INVNUM
instead.
PAYMENTREQUEST_n_NOT
IFYURL
NOTIFYURL (deprecated)
(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.You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
IMPORTANT:The notify URL applies only to DoExpressCheckoutPayment.
This value is ignored when set in SetExpressCheckout or
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
NOTIFYURL is deprecated since version 63.0. Use
PAYMENTREQUEST_0_NOTIFYURL instead.
PAYMENTREQUEST_n_NOT
ETEXT
NOTETEXT (deprecated)
(Optional) Note to the merchant. 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
NOTETEXT is deprecated since version 63.0. Use PAYMENTREQUEST_0_NOTETEXT
instead.
PAYMENTREQUEST_n_TRA
NSACTIONID
TRANSACTIONID
(deprecated)
(Optional) Transaction identification number of the transaction that was created.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
NOTE:This field is only returned after a successful transaction for
DoExpressCheckout has occurred.
TRANSACTIONID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_TRANSACTIONID instead.
PAYMENTREQUEST_n_ALL
OWEDPAYMENTMETHOD
ALLOWEDPAYMENTMETHOD
(deprecated)
(Optional) The payment method type. Specify the value InstantPaymentOnly.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
ALLOWEDPAYMENTMETHOD is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ALLOWEDPAYMENTMETHOD instead.
Field Description
Name-Value Pair API Developer Guide August 2012 71
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
Payment Details Item Type Fields
PAYMENTREQUEST_n_PAY
MENTACTION
PAYMENTACTION
(deprecated)
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. You can specify up to 10 payments, where n is
a digit between 0 and 9, inclusive; except for digital goods, which supports single
payments only. 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
PAYMENTACTION is deprecated since version 63.0. Use
PAYMENTREQUEST_0_PAYMENTACTION instead.
PAYMENTREQUEST_n_PAY
MENTREQUESTID
PAYMENTREQUESTID
(deprecated)
A unique identifier of the specific payment request, which is required for parallel
payments. 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
PAYMENTREQUESTID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_PAYMENTREQUESTID instead.
Field Description
L_PAYMENTREQUEST_n_NA
MEm
L_NAMEn (deprecated)
Item name. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment; except for digital goods, which supports single payments
only. These parameters must be ordered sequentially beginning with 0 (for
example L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0. L_NAMEn is deprecated since version 63.0.
Use L_PAYMENTREQUEST_0_NAMEm instead.
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
72 August 2012 Name-Value Pair API Developer Guide
L_PAYMENTREQUEST_n_DE
SCm
L_DESCn (deprecated)
(Optional) Item description. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment;
except for digital goods, which supports single payments only. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_DESC0, L_PAYMENTREQUEST_n_DESC1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0. L_DESCn is deprecated since version 63.0.
Use L_PAYMENTREQUEST_0_DESCm instead.
L_PAYMENTREQUEST_n_AM
Tm
L_AMTn (deprecated)
Cost of item. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed.You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment; except for digital goods, which supports single payments
only. These parameters must be ordered sequentially beginning with 0 (for
example L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).
NOTE:If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must
specify a value for PAYMENTREQUEST_n_ITEMAMT.
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. L_AMTn is deprecated since version 63.0.
Use L_PAYMENTREQUEST_0_AMTm instead.
L_PAYMENTREQUEST_n_NU
MBERm
L_NUMBERn (deprecated)
(Optional) Item number. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NUMBER0, L_PAYMENTREQUEST_n_NUMBER1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0. L_NUMBERn is deprecated since version
63.0. Use L_PAYMENTREQUEST_0_NUMBERm instead.
L_PAYMENTREQUEST_n_QT
Ym
L_QTYn (deprecated)
Item quantity. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. For digital goods
(L_PAYMENTREQUEST_n_ITEMCATEGORYm=Digital), this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive,
and m specifies the list item within the payment; except for digital goods, which
only supports single payments. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_QTY0,
L_PAYMENTREQUEST_n_QTY1).
Character length and limitations: Any positive integer
This field is introduced in version 53.0. L_QTYn is deprecated since version 63.0.
Use L_PAYMENTREQUEST_0_QTYm instead.
Field Description
Name-Value Pair API Developer Guide August 2012 73
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
L_PAYMENTREQUEST_n_TA
XAMTm
L_TAXAMTn (deprecated)
(Optional) Item sales tax. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment;
except for digital goods, which only supports single payments. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_TAXAMT0, L_PAYMENTREQUEST_n_TAXAMT1).
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 (,).
L_TAXAMTn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_TAXAMTm instead.
L_PAYMENTREQUEST_n_IT
EMWEIGHTVALUEm,
L_PAYMENTREQUEST_n_IT
EMWEIGHTUNITm
L_ITEMWEIGHTVALUEn and
L_ITEMWEIGHTUNITn
(deprecated)
(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. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment;. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE0,
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMWEIGHTTVALUEn and L_ITEMWEIGHTUNITn are deprecated since
version 63.0. Use L_PAYMENTREQUEST_0_ITEMWEIGHTVALUEm and
L_PAYMENTREQUEST_0_ITEMWEIGHTUNITm instead.
L_PAYMENTREQUEST_n_IT
EMLENGTHVALUEm,
L_PAYMENTREQUEST_n_IT
EMLENGTHUNITm
L_ITEMLENGTHVALUEn and
L_ITEMLENGHTUNITn
(deprecated)
(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. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters must
be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMLENGTHVALUE0,
L_PAYMENTREQUEST_n_ITEMLENGTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMLENGTHVALUEn and L_ITEMLENGTHUNITm are deprecated since version
63.0. Use L_PAYMENTREQUEST_0_ITEMLENGTHVALUEm and
L_PAYMENTREQUEST_0_ITEMLENGTHUNITn instead.
L_PAYMENTREQUEST_n_IT
EMWIDTHVALUEm,
L_PAYMENTREQUEST_n_IT
EMWIDTHUNITm
L_ITEMWIDTHVALUEn and
L_ITEMWIDTHUNITn
(deprecated)
(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.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive,
and m specifies the list item within the payment. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMWIDTHVALUE0,
L_PAYMENTREQUEST_n_ITEMWIDTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMWIDTHVALUEn and L_ITEMWIDTHUNITm are deprecated since version
63.0. Use L_PAYMENTREQUEST_0_ITEMWIDTHVALUEm and
L_PAYMENTREQUEST_0_ITEMWIDTHUNITn instead.
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
74 August 2012 Name-Value Pair API Developer Guide
Seller Details Type Fields
L_PAYMENTREQUEST_n_IT
EMHEIGHTVALUEm,
L_PAYMENTREQUEST_n_IT
EMHEIGHTUNITm
L_ITEMHEIGHTVALUEn and
L_ITEMHEIGHTUNITn
(deprecated)
(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. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters must
be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE0,
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMHEIGHTVALUEn and L_ITEMHEIGHTUNITm are deprecated since version
63.0. Use L_PAYMENTREQUEST_0_ITEMHEIGHTVALUEm and
L_PAYMENTREQUEST_0_ITEMHEIGHTUNITn instead.
L_PAYMENTREQUEST_n_IT
EMURLm
L_ITEMURLn (deprecated)
(Optional) URL for the item. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMURL0, L_PAYMENTREQUEST_n_ITEMURL1).
L_ITEMURLn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_ITEMURLm instead.
L_PAYMENTREQUEST_n_IT
EMCATEGORYm
Indicates whether an item is digital or physical. For digital goods, this field is
required and must be set to Digital. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive, and m specifies the list item within the
payment; except for digital goods, which only supports single payments. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMCATEGORY0,
L_PAYMENTREQUEST_n_ITEMCATEGORY1). It is one of the following values:
-Digital
-Physical
This field is available since version 65.1.
Field Description
PAYMENTREQUEST_n_SELL
ERPAYPALACCOUNTID
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. You can specify up
to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 127 single-byte alphanumeric characters
Field Description
Name-Value Pair API Developer Guide August 2012 75
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
Ebay Item Payment Details Item Type Fields
Buyer Details Fields
Field Description
L_PAYMENTREQUEST_n_EB
AYITEMNUMBERm
L_EBAYITEMNUMBERn
(deprecated)
(Optional) Auction item number. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive, and m specifies the list item within the payment.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_EBAYITEMNUMBER0,
L_PAYMENTREQUEST_n_EBAYITEMNUMBER1).
Character length: 765 single-byte characters
L_EBAYITEMNUMBERn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMNUMBERm instead.
L_PAYMENTREQUESST_n_E
BAYITEMAUCTIONTXNIDm
L_EBAYITEMAUCTIONTXNI
Dn (deprecated)
(Optional) Auction transaction identification number. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially beginning
with 0 (for example L_PAYMENTREQUEST_n_EBAYITEMAUCTIONTXNID0,
L_PAYMENTREQUEST_n_EBAYITEMAUCTIONTXNID1).
Character length: 255 single-byte characters
L_EBAYAUCTIONTXNIDn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYAUCTIONTXNIDm instead.
L_PAYMENTREQUEST_n_EB
AYITEMORDERIDm
L_EBAYITEMORDERIDn
(deprecated)
(Optional) Auction order identification number. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially beginning
with 0 (for example L_PAYMENTREQUEST_n_EBAYITEMORDERID0,
L_PAYMENTREQUEST_n_EBAYITEMORDERID1).
Character length: 64 single-byte characters
L_EBAYITEMORDERIDn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMORDERIDm instead.
L_PAYMENTREQUEST_n_EB
AYCARTIDm
L_EBAYITEMCARTIDn
(deprecated)
(Optional) The unique identifier provided by eBay for this order from the buyer.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive,
and m specifies the list item within the payment. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_EBAYITEMCARTID0,
L_PAYMENTREQUEST_n_EBAYITEMCARTID1).
Character length: 255 single-byte characters
L_EBAYITEMCARTIDn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMCARTIDm instead.
Field Description
BUYERID (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
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
76 August 2012 Name-Value Pair API Developer Guide
FundingSourceDetailsType Fields
Shipping Options Type Fields
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
Field Description
ALLOWPUSHFUNDING (Optional) Indicates whether the merchant can accept push funding. It is one of the
following values:
-0 – Merchant can accept push funding.
-1 – Merchant cannot accept push funding.
NOTE:This field overrides the setting in the merchant's PayPal account.
Field Description
L_SHIPPINGOPTIONISDEF
AULTn
Default shipping optio displayed on the PayPal pages. This field is required if you
specify the Callback URL. It is one of the following values:
-true – This is the default flat-rate shipping option. PayPal displays this option
and its amount by default.
-false – This flat-rate shipping option and its amount are not displayed as the
default.
NOTE:There must be ONE and ONLY ONE default. It is not OK to have no
default.
L_SHIPPINGOPTIONNAMEnInternal 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.
L_SHIPPINGOPTIONAMOUN
Tn
Amount of the flat rate shipping option. This field is required if you specify the
Callback URL.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
Field Description
Name-Value Pair API Developer Guide August 2012 77
ExpressCheckout API Operations
SetExpressCheckout API Operation 6
Billing Agreement Details Type Fields
Field Description
L_BILLINGTYPEn(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.
BILLINGTYPE Type of billing agreement for reference transactions. You must have permission from
PayPal to use this field.
For reference transactions, 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.
Other defined values are not valid.
L_BILLINGAGREEMENTD
ESCRIPTIONn
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
L_PAYMENTTYPEn(Optional) Type of PayPal payment you require for the billing agreement. It is one of
the following values:
-Any
-InstantOnly
NOTE:For recurring payments, this field is ignored.
L_BILLINGAGREEMENTC
USTOMn
(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
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
78 August 2012 Name-Value Pair API Developer Guide
Tax Id Details Type Fields
SetExpressCheckout Response Message
SetExpressCheckout Response Fields
GetExpressCheckoutDetails API Operation
The GetExpressCheckoutDetails API operation obtains information about an Express
Checkout transaction.
GetExpressCheckoutDetails Request Message
GetExpressCheckoutDetails Request Fields
Field Description
TAXIDTYPE 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.
TAXIDDETAILS Buyer’s tax ID. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14
single-byte characters for businesses.
This field is introduced in API version 72.0.
Field Description
TOKEN 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
Field Description
METHOD (Required) Must be GetExpressCheckoutDetails.
Name-Value Pair API Developer Guide August 2012 79
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
GetExpressCheckoutDetails Response Message
GetExpressCheckoutDetails Response Fields
TOKEN (Required) A timestamped token, the value of which was returned by
SetExpressCheckout response.
Character length and limitations: 20 single-byte characters
Field Description
TOKEN The timestamped token value that was returned by SetExpressCheckout response
and passed on GetExpressCheckoutDetails request.
Character length and limitations: 20 single-byte characters
CUSTOM 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
INVNUM 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
PHONENUM Buyer’s contact phone number.
NOTE:PayPal returns a contact phone number only if your Merchant Account
Profile settings require that the buyer enter one.
Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers)
or +XXX XXXXXXXX (for international numbers)
PAYPALADJUSTMENT 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 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 Flag to indicate whether you need to redirect the buyer back to PayPal after
successfully completing the transaction.
NOTE:Use this field only if you are using giropay or bank transfer payment methods
in Germany.
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
80 August 2012 Name-Value Pair API Developer Guide
Payer Information Fields
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 Gift message entered by the buyer on the PayPal checkout pages.
Character length and limitations: 150 single-byte characters
GIFTRECEIPTENABLE 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 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 Returns the gift wrap amount only if the buyer selects the gift option on the PayPal
pages.
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 Buyer’s email address if the buyer provided it on the PayPal pages.
Character length and limitations: 127 single-byte characters
SURVEYQUESTION Survey question on the PayPal checkout pages.
Character length and limitations: 50 single-byte characters
SURVEYCHOICESELECTE
D
Survey response the buyer selects on the PayPal pages.
Character length and limitations: 15 single-byte characters
Field Description
EMAIL Email address of buyer.
Character length and limitations: 127 single-byte characters
PAYERID Unique PayPal Customer Account identification number.
Character length and limitations: 13 single-byte alphanumeric characters
PAYERSTATUS Status of buyer. It is one of the following values:
-verified
-unverified
Character length and limitations: 10 single-byte alphabetic characters
Field Description
Name-Value Pair API Developer Guide August 2012 81
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
Payer Name Fields
Address Type Fields
COUNTRYCODE Buyer’s country of residence in the form of ISO standard 3166 two-character country
codes.
Character length and limitations: 2 single-byte characters
BUSINESS Buyer’s business name.
Character length and limitations: 127 single-byte characters
Field Description
SALUTATION Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FIRSTNAME Buyer’s first name.
Character length and limitations: 25 single-byte characters
MIDDLENAME Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LASTNAME Buyer’s last name.
Character length and limitations: 25 single-byte characters
SUFFIX Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
PAYMENTREQUEST_n_SHIPTONAM
E
SHIPTONAME (deprecated)
Person’s name associated with this shipping address. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 32 single-byte characters
SHIPTONAME is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTONAME instead.
PAYMENTREQUEST_n_SHIPTOSTR
EET
SHIPTOSTREET (deprecated)
First street address. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET instead.
PAYMENTREQUEST_n_SHIPTOSTR
EET2
SHIPTOSTREET2 (deprecated)
Second street address. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET2 instead.
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
82 August 2012 Name-Value Pair API Developer Guide
Payment Details Type 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.
PAYMENTREQUEST_n_SHIPTOCIT
Y
SHIPTOCITY (deprecated)
Name of city. You can specify up to 10 payments, where n is a digit between
0 and 9, inclusive.
Character length and limitations: 40 single-byte characters
SHIPTOCITY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCITY instead.
PAYMENTREQUEST_n_SHIPTOSTA
TE
SHIPTOSTATE (deprecated)
State or province. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTATE instead.
PAYMENTREQUEST_n_SHIPTOZIP
SHIPTOZIP (deprecated)
U.S. ZIP code or other country-specific postal code. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 20 single-byte characters
SHIPTOZIP is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOZIP instead.
PAYMENTREQUEST_n_SHIPTOCOU
NTRYCODE
SHIPTOCOUNTRY (deprecated)
Country code. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
Character length and limitations: 2 single-byte characters
SHIPTOCOUNTRY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE instead.
PAYMENTREQUEST_n_SHIPTOPHO
NENUM
SHIPTOPHONENUM (deprecated)
Phone number. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOPHONENUM instead.
PAYMENTREQUEST_n_ADDRESSST
ATUS
ADDRESSSTATUS (deprecated)
Status of street address on file with PayPal. 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
-Confirmed
-Unconfirmed
ADDRESSSTATUS is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ADDRESSSTATUS instead.
Field Description
Name-Value Pair API Developer Guide August 2012 83
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
Field Description
PAYMENTREQUEST_n_AMT
AMT (deprecated)
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. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive; except for digital
goods, which supports single payments only. For digital goods, the following
must be true:
-total cost > 0
-total cost <= total cost passed in the call to SetExpressCheckout
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 (,).
AMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_AMT instead.
PAYMENTREQUEST_n_CURRE
NCYCODE
CURRENCYCODE (deprecated)
A 3-character currency code. Default: USD.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive.
CURRENCYCODE is deprecated since version 63.0. Use
PAYMENTREQUEST_n_CURRENCYCODE instead.
PAYMENTREQUEST_n_ITEMA
MT
ITEMAMT (deprecated)
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. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive; except for digital goods, which supports single
payments only.
NOTE:PAYMENTREQUEST_n_ITEMAMT is required if you specify
L_PAYMENTREQUEST_n_AMTm.
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 (,).
ITEMAMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_ITEMAMT
instead.
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
84 August 2012 Name-Value Pair API Developer Guide
PAYMENTREQUEST_n_SHIPP
INGAMT
SHIPPINGAMT (deprecated)
(Optional) Total shipping costs for this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
NOTE:If you specify a value for PAYMENTREQUEST_n_SHIPPINGAMT, you
must also specify a value for PAYMENTREQUEST_n_ITEMAMT.
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 (,).
SHIPPINGAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGAMT instead.
PAYMENTREQUEST_n_INSUR
ANCEAMT
INSURANCEAMT (deprecated)
(Optional) Total shipping insurance costs for this order. The value must be a
non-negative currency amount or null if insurance options are offered. 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 (,).
INSURANCEAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_INSURANCEAMT instead.
PAYMENTREQUEST_n_SHIPD
ISCAMT
SHIPPINGDISCAMT
(deprecated)
(Optional) Shipping discount for this order, specified as a negative number. 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 (,).
SHIPPINGDISCAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGDISCAMT instead.
PAYMENREQUEST_n_INSURA
NCEOPTIONOFFERED
INSURANCEOPTIONOFFERED
(deprecated)
(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal pages. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive. 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.’
INSURANCEOPTIONOFFERED is deprecated since version 63.0. Use
PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED instead.
Field Description
Name-Value Pair API Developer Guide August 2012 85
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
PAYMENTREQUEST_n_HANDL
INGAMT
HANDLINGAMT (deprecated)
(Optional) Total handling costs for this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
NOTE:If you specify a value for PAYMENTREQUEST_n_HANDLINGAMT, you
must also specify a value for PAYMENTREQUEST_n_ITEMAMT.
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 (,).
HANDLINGAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_HANDLINGAMT instead.
PAYMENTREQUEST_n_TAXAM
T
TAXAMT (deprecated)
(Optional) Sum of tax for all items in this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
NOTE:PAYMENTREQUEST_n_TAXAMT is required if you specify
L_PAYMENTREQUEST_n_TAXAMTm
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 (,).
TAXAMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_TAXAMT
instead.
PAYMENTREQUEST_n_DESC
DESC (deprecated)
(Optional) Description of items the buyer is purchasing. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive; except for digital
goods, which supports single payments only.
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
DESC is deprecated since version 63.0. Use PAYMENTREQUEST_0_DESC instead.
PAYMENTREQUEST_n_CUSTO
M
CUSTOM (deprecated)
(Optional) A free-form field for your own use. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
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
CUSTOM is deprecated since version 63.0. Use PAYMENTREQUEST_0_CUSTOM
instead.
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
86 August 2012 Name-Value Pair API Developer Guide
PAYMENTREQUEST_n_INVNU
M
INVNUM (deprecated)
(Optional) Your own invoice or tracking number.You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
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
INVNUM is deprecated since version 63.0. Use PAYMENTREQUEST_0_INVNUM
instead.
PAYMENTREQUEST_n_NOTIF
YURL
NOTIFYURL (deprecated)
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.
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. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
IMPORTANT:The notify URL applies only to
DoExpressCheckoutPayment. This value is ignored when
set in SetExpressCheckout or
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
NOTIFYURL is deprecated since version 63.0. Use
PAYMENTREQUEST_0_NOTIFYURL instead.
PAYMENTREQUEST_n_NOTET
EXT
NOTETEXT (deprecated)
Note to the merchant. 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
NOTETEXT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_NOTETEXT instead.
PAYMENTREQUEST_n_TRANS
ACTIONID
TRANSACTIONID (deprecated)
Transaction identification number of the transaction that was created.You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
NOTE:This field is only returned after a successful transaction for
DoExpressCheckout has occurred.
TRANSACTIONID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_TRANSACTIONID instead.
PAYMENTREQUEST_n_ALLOW
EDPAYMENTMETHOD
ALLOWEDPAYMENTMETHOD
(deprecated)
The payment method type. Specify the value InstantPaymentOnly. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
ALLOWEDPAYMENTMETHOD is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ALLOWEDPAYMENTMETHOD instead.
Field Description
Name-Value Pair API Developer Guide August 2012 87
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
Payment Details Item Type Fields
PAYMENTREQUEST_n_PAYME
NTREQUESTID
PAYMENTREQUESTID
(deprecated)
A unique identifier of the specific payment request. Required when
implementing parallel payments. 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
PAYMENTREQUESTID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_PAYMENTREQUESTID instead.
Field Description
L_PAYMENTREQUEST_n_NAME
m
L_NAMEn (deprecated)
Item name. You can specify up to 10 payments, where n is a digit between 0 and
9, inclusive, and m specifies the list item within the payment; except for digital
goods, which only supports single payments. These parameters must be ordered
sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_NAME0,
L_PAYMENTREQUEST_n_NAME1).
Character length and limitations: 127 single-byte characters
L_NAMEn is deprecated in version 63.0. Use L_PAYMENTREQUEST_0_NAMEm
instead.
L_PAYMENTREQUEST_n_DESC
m
L_DESCn (deprecated)
Item description. You can specify up to 10 payments, where n is a digit between
0 and 9, inclusive, and m specifies the list item within the payment; except for
digital goods, which only supports single payments.
Character length and limitations: 127 single-byte characters
This field is available since version 53.0. L_DESCn is deprecated in version
63.0. Use L_PAYMENTREQUEST_0_DESCm instead.
L_PAYMENTREQUEST_n_AMT
m
L_AMTn (deprecated)
Cost of item. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive, and m specifies the list item within the payment; except for
digital goods, which only supports single payments. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).
NOTE:If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must
specify a value for PAYMENTREQUEST_n_ITEMAMT.
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 (,).
L_AMTn is deprecated in version 63.0. Use L_PAYMENTREQUEST_0_AMTm
instead.
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
88 August 2012 Name-Value Pair API Developer Guide
L_PAYMENTREQUEST_n_NUMB
ERm
L_NUMBERn (deprecated)
Item number. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NUMBER0, L_PAYMENTREQUEST_n_NUMBER1).
Character length and limitations: 127 single-byte characters
L_NUMBERn is deprecated in version 63.0. Use
L_PAYMENTREQUEST_0_NUMBERm instead.
L_PAYMENTREQUEST_n_QTY
m
L_QTYn (deprecated)
Item quantity. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).
Character length and limitations: Any positive integer
L_QTYn is deprecated in version 63.0. Use L_PAYMENTREQUEST_0_QTYm
instead.
L_PAYMENTREQUEST_n_TAXA
MTm
L_TAXAMTn (deprecated)
Item sales tax. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_TAXAMT0, L_PAYMENTREQUEST_n_TAXAMT1).
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 (,).
L_TAXAMTn is deprecated in version 63.0. Use
L_PAYMENTREQUEST_0_TAXAMTm instead.
L_PAYMENTREQUEST_n_ITEM
WEIGHTVALUEm,
L_PAYMENTREQUEST_n_ITEM
WEIGHTUNITm
L_ITEMWEIGHTVALUEn and
L_ITEMWEIGHTUNITn
(deprecated)
Weight of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE0,
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMWEIGTHTVALUEn and L_ITEMWEIGHTUNITn are deprecated in version
63.0. Use L_PAYMENTREQUEST_0_ITEMWEIGTHTVALUEm and
L_PAYMENTREQUEST_0_ITEMWEIGHTUNITminstead.
L_PAYMENTREQUEST_n_ITEM
LENGTHVALUEm,
L_PAYMENTREQUEST_n_ITEM
LENGTHUNITm
L_ITEMLENGTHVALUEn and
L_ITEMLENGTHUNITn
(deprecated)
Length of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMLENGTHVALUE0,
L_PAYMENTREQUEST_n_ITEMLENGTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMLENGTHVALUEn and L_ITEMLENGTHUNITn are deprecated in version
63.0. Use L_PAYMENTREQUEST_0_ITEMLENGTHVALUEm and
L_PAYMENTREQUEST_0_ITEMLENGTHUNITm instead.
Field Description
Name-Value Pair API Developer Guide August 2012 89
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
EbayItemPaymentDetailsItemType Fields
L_PAYMENTREQUEST_n_ITEM
WIDTHVALUEm,
L_PAYMENTREQUEST_n_ITEM
WIDTHUNITm
L_ITEMWIDTHVALUEn and
L_ITEMWIDTHUNITn
(deprecated)
Width of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMWIDTHVALUE0,
L_PAYMENTREQUEST_n_ITEMWIDTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMWIDTHVALUEn and L_ITEMWIDTHUNITn are deprecated in version
63.0. Use L_PAYMENTREQUEST_n_ITEMWIDTHVALUEm and
L_PAYMENTREQUEST_n_ITEMWIDTHUNITm instead.
L_PAYMENTREQUEST_n_ITEM
HEIGHTVALUEm,
L_PAYMENTREQUEST_n_ITEM
HEIGHTUNITm
L_ITEMHEIGHTVALUEn and
L_ITEMHEIGHTUNITn
(deprecated)
Height of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE0,
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMHEIGHTVALUEn and L_ITEMHEIGHTUNITn are deprecated in version
63.0. Use L_PAYMENTREQUEST_n_ITEMHEIGHTVALUEm and
L_ITEMHEIGHTUNITm instead.
L_PAYMENTREQUEST_n_ITEM
CATEGORYm
Indicates whether the item is digital or physical. For digital goods
(L_PAYMENTREQUEST_n_ITEMCATEGORYm=Digital), this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMCATEGORY0,
L_PAYMENTREQUEST_n_ITEMCATEGORY1). It is one of the following values:
-Digital
-Physical
This field is available since version 65.1.
Field Description
L_PAYMENTREQUEST_n_EB
AYITEMNUMBERm
EBAYITEMNUMBERn
(deprecated)
Auction item number. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment.
Character length: 765 single-byte characters
EBAYITEMNUMBERn is deprecated since 63.0. Use
L_PAYMENTREQUEST_0_EBAYAUCTIONTXNIDm instead.
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
90 August 2012 Name-Value Pair API Developer Guide
User Selected Options Type Fields
L_PAYMENTREQUEST_n_EB
AYITEMAUCTIONTXNIDm
EBAYITEMAUCTIONTXNIDn
(deprecated)
Auction transaction identification number. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive, and m specifies the list item within
the payment.
Character length: 255 single-byte characters
EBAYITEMAUCTIONTXNIDn is deprecated since 63.0. Use
L_PAYMENTREQUEST_0_EBAYAUCTIONTXNIDm instead.
L_PAYMENTREQUEST_n_EB
AYITEMORDERIDm
EBAYITEMORDERIDn
(deprecated)
Auction order identification number. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive, and m specifies the list item within the
payment.
Character length: 64 single-byte characters
EBAYITEMORDERIDn is deprecated since 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMORDERIDm instead.
L_PAYMENTREQUEST_n_EB
AYITEMCARTIDm
EBAYITEMCARTIDn
(deprecated)
The unique identifier provided by eBay for this order from the buyer. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m
specifies the list item within the payment.
Character length: 255 single-byte characters
EBAYITEMCARTIDn is deprecated since 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMCARTIDm instead.
Field Description
SHIPPINGCALCULATIONM
ODE
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
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
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 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 The name of the shipping option, such as air or ground.
Field Description
Name-Value Pair API Developer Guide August 2012 91
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation 6
Seller Details Type Fields
Payment Request Info Type Fields
Payment Error Type Fields
Field Description
PAYMENTREQUEST_n_SELLER
PAYPALACCOUNTID
Unique identifier for the merchant. For parallel payments, this field contains
either the Payer Id or the email address of the merchant. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 127 single-byte alphanumeric characters
Field Description
PAYMENTREQUEST_n_TRAN
SACTIONID
Transaction ID for up to 10 parallel payment requests. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
This field is available since version 64.0.
PAYMENTREQUEST_n_PAYM
ENTREQUESTID
Payment request ID. You can specify up to 10 payments, where n is a digit between
0 and 9, inclusive.
This field is available since version 64.0.
Field Description
PAYMENTREQUEST_n_SH
ORTMESSAGE
xs:string
Payment error short message. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
PAYMENTREQUEST_n_LO
NGMESSAGE
xs:string
Payment error long message. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
PAYMENTREQUEST_n_ER
RORCODE
xs:string
Payment error code. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive.
PAYMENTREQUEST_n_SE
VERITYCODE
xs:string
Payment error severity code. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
PAYMENTREQUEST_n_AC
K
xs:string
Application-specific error values indicating more about the error condition. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
92 August 2012 Name-Value Pair API Developer Guide
Tax Id Details Type Fields
DoExpressCheckoutPayment API Operation
The DoExpressCheckoutPayment API operation completes an Express Checkout
transaction.
If you set up a billing agreement in your SetExpressCheckout API call, the billing
agreement is created when you call the DoExpressCheckoutPayment API operation.
DoExpressCheckoutPayment Request Message
DoExpressCheckoutPayment Request Fields
Field Description
TAXIDTYPE 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.
TAXIDDETAILS Buyer’s tax ID. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14
single-byte characters for businesses.
This field is introduced in API version 72.0.
Field Description
METHOD (Required) Must be DoExpressCheckoutPayment.
TOKEN (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
Name-Value Pair API Developer Guide August 2012 93
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
PAYMENTACTION
(deprecated)
(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 PAYMENTREQUEST_n_PAYMENTACTION instead.
PAYERID (Required) Unique PayPal buyer account identification number as returned in the
GetExpressCheckoutDetails response
Character length and limitations: 13 single-byte alphanumeric characters
RETURNFMFDETAILS (Optional) Flag to indicate whether you want the results returned by Fraud
Management Filters. By default, you do not receive this information. It is one of the
following values:
-0 – Do not receive FMF details (default).
-1 – Receive FMF details.
GIFTMESSAGE (Optional) The gift message the buyer entered on the PayPal pages.
Character length and limitations: 150 single-byte characters
GIFTRECEIPTENABLE (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 (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 (Optional) Amount only if the buyer selected the gift option on the PayPal pages.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
BUYERMARKETINGEMAIL (Optional) The buyer email address opted in by the buyer on the PayPal pages.
Character length and limitations: 127 single-byte characters
SURVEYQUESTION (Optional) Survey question on the PayPal pages.
Limitations: 50 single-byte characters
SURVEYCHOICESELECTE
D
(Optional) Survey response that the buyer selected on the PayPal pages.
Character length and limitations: 15 single-byte characters
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
94 August 2012 Name-Value Pair API Developer Guide
Payment Details Type 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.
BUTTONSOURCE (Optional) Identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
Field Description
PAYMENTREQUEST_n_AMT
AMT (deprecated)
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. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive; except for digital goods, which supports single
payments only. For digital goods, the following must be true:
-total cost > 0
-total cost <= total cost passed in the call to SetExpressCheckout
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 (,).
AMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_AMT instead.
PAYMENTREQUEST_n_CURRENC
YCODE
CURRENCYCODE (deprecated)
(Optional) A 3-character currency code. Default: USD.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive.
CURRENCYCODE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_CURRENCYCODE instead.
Field Description
Name-Value Pair API Developer Guide August 2012 95
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
PAYMENTREQUEST_n_ITEMAMT
ITEMAMT (deprecated)
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. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive; except for digital goods, which supports single
payments only.
NOTE:PAYMENTREQUEST_n_ITEMAMT is required if you specify
L_PAYMENTREQUEST_n_AMTm.
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 (,).
ITEMAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ITEMAMT instead.
PAYMENTREQUEST_n_SHIPPIN
GAMT
SHIPPINGAMT (deprecated)
(Optional) Total shipping costs for this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
NOTE:If you specify a value for PAYMENTREQUEST_n_SHIPPINGAMT, you
must also specify a value for PAYMENTREQUEST_n_ITEMAMT.
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 (,).
SHIPPINGAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGAMT instead.
PAYMENTREQUEST_n_INSURAN
CEAMT
INSURANCEAMT (deprecated)
(Optional) Total shipping insurance costs for this order. The value must be a
non-negative currency amount or null if insurance options are offered. 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 (,).
INSURANCEAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_INSURANCEAMT instead.
PAYMENTREQUEST_n_SHIPDIS
CAMT
SHIPPINGDISCAMT
(deprecated)
(Optional) Shipping discount for this order, specified as a negative number.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive.
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 (,).
SHIPPINGDISCAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGDISCAMT instead.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
96 August 2012 Name-Value Pair API Developer Guide
PAYMENTREQUEST_n_INSURAN
CEOPTIONOFFERED
INSURANCEOPTIONOFFERED
(deprecated)
(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal Review page. You can specify up to 10 payments, where
n is a digit between 0 and 9, inclusive. 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.’
INSURANCEOPTIONOFFERED is deprecated since version 63.0. Use
PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED instead.
PAYMENTREQUEST_n_HANDLIN
GAMT
HANDLINGAMT (deprecated)
(Optional) Total handling costs for this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
NOTE:If you specify a value for PAYMENTREQUEST_n_HANDLINGAMT, you
must also specify a value for PAYMENTREQUEST_n_ITEMAMT.
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 (,).
HANDLINGAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_HANDLINGAMT instead.
PAYMENTREQUEST_n_TAXAMT
TAXAMT (deprecated)
(Optional) Sum of tax for all items in this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital
goods, which supports single payments only.
NOTE:PAYMENTREQUEST_n_TAXAMT is required if you specify
L_PAYMENTREQUEST_n_TAXAMTm
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 (,).
TAXAMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_TAXAMT
instead.
PAYMENTREQUEST_n_DESC
DESC (deprecated)
(Optional) Description of items the buyer is purchasing. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive; except for digital
goods, which supports single payments only.
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
DESC is deprecated since version 63.0. Use PAYMENTREQUEST_0_DESC
instead.
Field Description
Name-Value Pair API Developer Guide August 2012 97
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
PAYMENTREQUEST_n_CUSTOM
CUSTOM (deprecated)
(Optional) A free-form field for your own use. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
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
CUSTOM is deprecated since version 63.0. Use PAYMENTREQUEST_0_CUSTOM
instead.
PAYMENTREQUEST_n_INVNUM
INVNUM (deprecated)
(Optional) Your own invoice or tracking number.You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital
goods, which supports single payments only.
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
INVNUM is deprecated since version 63.0. Use PAYMENTREQUEST_0_INVNUM
instead.
PAYMENTREQUEST_n_NOTIFYU
RL
NOTIFYURL (deprecated)
(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.
(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. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive.
IMPORTANT:The notify URL applies only to
DoExpressCheckoutPayment. This value is ignored when
set in SetExpressCheckout or
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
NOTIFYURL is deprecated since version 63.0. Use
PAYMENTREQUEST_0_NOTIFYURL instead.
PAYMENTREQUEST_n_NOTETEX
T
NOTETEXT (deprecated)
(Optional) Note to the merchant. 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
NOTETEXT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_NOTETEXT instead.
PAYMENTREQUEST_n_SOFTDES
CRIPTOR
SOFTDESCRIPTOR (deprecated)
A per transaction description of the payment that is passed to the buyer’s credit
card statement. You can specify up to 10 payments, where n is a digit between
0 and 9, inclusive.
NOTE:Ignore when PAYMENTREQUEST_n_PAYMENTACTION=Order.
SOFTDESCRIPTOR is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SOFTDESCRIPTOR instead.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
98 August 2012 Name-Value Pair API Developer Guide
PAYMENTREQUEST_n_TRANSAC
TIONID
TRANSACTIONID (deprecated)
(Optional) Transaction identification number of the transaction that was
created.You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive.
NOTE:This field is only returned after a successful transaction for
DoExpressCheckout has occurred.
TRANSACTIONID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_TRANSACTIONID instead.
PAYMENTREQUEST_n_ALLOWED
PAYMENTMETHOD
ALLOWEDPAYMENTMETHOD
(deprecated)
(Optional) The payment method type. Specify the value
InstantPaymentOnly. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
ALLOWEDPAYMENTMETHOD is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ALLOWEDPAYMENTMETHOD instead.
PAYMENTREQUEST_n_PAYMENT
ACTION
PAYMENTACTION (deprecated)
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. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital
goods, which supports single payments only. 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
PAYMENTACTION is deprecated since version 63.0. Use
PAYMENTREQUEST_0_PAYMENTACTION instead.
PAYMENTREQUEST_n_PAYMENT
REQUESTID
PAYMENTREQUESTID
(deprecated)
A unique identifier of the specific payment request. Required when
implementing parallel payments. 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
PAYMENTREQUESTID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_PAYMENTREQUESTID instead.
Field Description
Name-Value Pair API Developer Guide August 2012 99
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
Address Fields
Field Description
PAYMENTREQUEST_n_SHIPTONAM
E
SHIPTONAME (deprecated)
Person’s name associated with this shipping address. It is required if using a
shipping address. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
Character length and limitations: 32 single-byte characters
SHIPTONAME is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTONAME instead.
PAYMENTREQUEST_n_SHIPTOSTR
EET
SHIPTOSTREET (deprecated)
First street address. It is required if using a shipping address. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET instead.
PAYMENTREQUEST_n_SHIPTOSTR
EET2
SHIPTOSTREET2 (deprecated)
(Optional) Second street address. You can specify up to 10 payments, where
n is a digit between 0 and 9, inclusive.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET2 instead.
PAYMENTREQUEST_n_SHIPTOCIT
Y
SHIPTOCITY (deprecated)
Name of city. It is required if using a shipping address. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 40 single-byte characters
SHIPTOCITY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCITY instead.
PAYMENTREQUEST_n_SHIPTOSTA
TE
SHIPTOSTATE (deprecated)
State or province. It is required if using a shipping address. You can specify
up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTATE instead.
PAYMENTREQUEST_n_SHIPTOZIP
SHIPTOZIP (deprecated)
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. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 20 single-byte characters
SHIPTOZIP is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOZIP instead.
PAYMENTREQUEST_n_SHIPTOCOU
NTRYCODE
SHIPTOCOUNTRY (deprecated)
Country code. It is required if using a shipping address. You can specify up
to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 2 single-byte characters
SHIPTOCOUNTRY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE instead.
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
100 August 2012 Name-Value Pair API Developer Guide
Payment Details Item Type Fields
PAYMENTREQUEST_n_SHIPTOPHO
NENUM
SHIPTOPHONENUM (deprecated)
(Optional) Phone number. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive.
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOPHONENUM instead.
Field Description
L_PAYMENTREQUEST_n_NA
MEm
L_NAMEn (deprecated)
Item name. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment; except for digital goods, which supports single payments
only. These parameters must be ordered sequentially beginning with 0 (for
example L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0. L_NAMEn is deprecated since version 63.0.
Use L_PAYMENTREQUEST_0_NAMEm instead.
L_PAYMENTREQUEST_n_DE
SCm
L_DESCn (deprecated)
(Optional) Item description. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment;
except for digital goods, which supports single payments only. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_DESC0, L_PAYMENTREQUEST_n_DESC1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0. L_DESCn is deprecated since version 63.0.
Use L_PAYMENTREQUEST_0_DESCm instead.
L_PAYMENTREQUEST_n_AM
Tm
L_AMTn (deprecated)
Cost of item. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed.You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment; except for digital goods, which supports single payments
only. These parameters must be ordered sequentially beginning with 0 (for
example L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).
NOTE:If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must
specify a value for PAYMENTREQUEST_n_ITEMAMT.
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. L_AMTn is deprecated since version 63.0.
Use L_PAYMENTREQUEST_0_AMTm instead.
Field Description
Name-Value Pair API Developer Guide August 2012 101
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
L_PAYMENTREQUEST_n_NU
MBERm
L_NUMBERn (deprecated)
(Optional) Item number. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NUMBER0, L_PAYMENTREQUEST_n_NUMBER1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0. L_NUMBERn is deprecated since version
63.0. Use L_PAYMENTREQUEST_0_NUMBERm instead.
L_PAYMENTREQUEST_n_QT
Ym
L_QTYn (deprecated)
Item quantity. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. For digital goods
(L_PAYMENTREQUEST_n_ITEMCATEGORYm=Digital), this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive,
and m specifies the list item within the payment; except for digital goods, which
only supports single payments. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_QTY0,
L_PAYMENTREQUEST_n_QTY1).
Character length and limitations: Any positive integer
This field is introduced in version 53.0. L_QTYn is deprecated since version 63.0.
Use L_PAYMENTREQUEST_0_QTYm instead.
L_PAYMENTREQUEST_n_TA
XAMTm
L_TAXAMTn (deprecated)
(Optional) Item sales tax. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment;
except for digital goods, which only supports single payments. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_TAXAMT0, L_PAYMENTREQUEST_n_TAXAMT1).
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 (,).
L_TAXAMTn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_TAXAMTm instead.
L_PAYMENTREQUEST_n_IT
EMWEIGHTVALUEm,
L_PAYMENTREQUEST_n_IT
EMWEIGHTUNITm
L_ITEMWEIGHTVALUEn and
L_ITEMWEIGHTUNITn
(deprecated)
(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. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment;. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE0,
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMWEIGHTTVALUEn and L_ITEMWEIGHTUNITn are deprecated since
version 63.0. Use L_PAYMENTREQUEST_0_ITEMWEIGHTVALUEm and
L_PAYMENTREQUEST_0_ITEMWEIGHTUNITm instead.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
102 August 2012 Name-Value Pair API Developer Guide
L_PAYMENTREQUEST_n_IT
EMLENGTHVALUEm,
L_PAYMENTREQUEST_n_IT
EMLENGTHUNITm
L_ITEMLENGTHVALUEn and
L_ITEMLENGHTUNITn
(deprecated)
(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. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters must
be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMLENGTHVALUE0,
L_PAYMENTREQUEST_n_ITEMLENGTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMLENGTHVALUEn and L_ITEMLENGTHUNITm are deprecated since version
63.0. Use L_PAYMENTREQUEST_0_ITEMLENGTHVALUEm and
L_PAYMENTREQUEST_0_ITEMLENGTHUNITn instead.
L_PAYMENTREQUEST_n_IT
EMWIDTHVALUEm,
L_PAYMENTREQUEST_n_IT
EMWIDTHUNITm
L_ITEMWIDTHVALUEn and
L_ITEMWIDTHUNITn
(deprecated)
(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.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive,
and m specifies the list item within the payment. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMWIDTHVALUE0,
L_PAYMENTREQUEST_n_ITEMWIDTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMWIDTHVALUEn and L_ITEMWIDTHUNITm are deprecated since version
63.0. Use L_PAYMENTREQUEST_0_ITEMWIDTHVALUEm and
L_PAYMENTREQUEST_0_ITEMWIDTHUNITn instead.
L_PAYMENTREQUEST_n_IT
EMHEIGHTVALUEm,
L_PAYMENTREQUEST_n_IT
EMHEIGHTUNITm
L_ITEMHEIGHTVALUEn and
L_ITEMHEIGHTUNITn
(deprecated)
(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. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters must
be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE0,
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMHEIGHTVALUEn and L_ITEMHEIGHTUNITm are deprecated since version
63.0. Use L_PAYMENTREQUEST_0_ITEMHEIGHTVALUEm and
L_PAYMENTREQUEST_0_ITEMHEIGHTUNITn instead.
L_PAYMENTREQUEST_n_IT
EMURLm
L_ITEMURLn (deprecated)
(Optional) URL for the item. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMURL0, L_PAYMENTREQUEST_n_ITEMURL1).
L_ITEMURLn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_ITEMURLm instead.
Field Description
Name-Value Pair API Developer Guide August 2012 103
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
EbayItemPaymentDetailsItemType Fields
L_PAYMENTREQUEST_n_IT
EMCATEGORYm
Indicates whether an item is digital or physical. For digital goods, this field is
required and must be set to Digital. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive, and m specifies the list item within the
payment; except for digital goods, which only supports single payments. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMCATEGORY0,
L_PAYMENTREQUEST_n_ITEMCATEGORY1). It is one of the following values:
-Digital
-Physical
This field is available since version 65.1.
Field Description
L_PAYMENTREQUEST_n_EB
AYITEMNUMBERm
L_EBAYITEMNUMBERn
(deprecated)
(Optional) Auction item number. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive, and m specifies the list item within the payment.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_EBAYITEMNUMBER0,
L_PAYMENTREQUEST_n_EBAYITEMNUMBER1).
Character length: 765 single-byte characters
L_EBAYITEMNUMBERn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMNUMBERm instead.
L_PAYMENTREQUESST_n_E
BAYITEMAUCTIONTXNIDm
L_EBAYITEMAUCTIONTXNI
Dn (deprecated)
(Optional) Auction transaction identification number. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially beginning
with 0 (for example L_PAYMENTREQUEST_n_EBAYITEMAUCTIONTXNID0,
L_PAYMENTREQUEST_n_EBAYITEMAUCTIONTXNID1).
Character length: 255 single-byte characters
L_EBAYAUCTIONTXNIDn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYAUCTIONTXNIDm instead.
L_PAYMENTREQUEST_n_EB
AYITEMORDERIDm
L_EBAYITEMORDERIDn
(deprecated)
(Optional) Auction order identification number. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially beginning
with 0 (for example L_PAYMENTREQUEST_n_EBAYITEMORDERID0,
L_PAYMENTREQUEST_n_EBAYITEMORDERID1).
Character length: 64 single-byte characters
L_EBAYITEMORDERIDn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMORDERIDm instead.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
104 August 2012 Name-Value Pair API Developer Guide
UserSelectedOptions Fields
Seller Details Type Fields
L_PAYMENTREQUEST_n_EB
AYCARTIDm
L_EBAYITEMCARTIDn
(deprecated)
(Optional) The unique identifier provided by eBay for this order from the buyer.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive,
and m specifies the list item within the payment. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_EBAYITEMCARTID0,
L_PAYMENTREQUEST_n_EBAYITEMCARTID1).
Character length: 255 single-byte characters
L_EBAYITEMCARTIDn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMCARTIDm instead.
Field Description
INSURANCEOPTIONSELEC
TED
(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
(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 (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 (Optional) The name of the shipping option, such as air or ground.
Field Description
PAYMENTREQUEST_n_SELL
ERID
SELLERID (deprecated)
(Optional) Unique non-changing identifier for the merchant at the marketplace
site. This ID is not displayed. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive.
Character length and limitations: 13 single-byte alphanumeric characters
SELLERID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SELLERID instead.
Field Description
Name-Value Pair API Developer Guide August 2012 105
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
DoExpressCheckoutPayment Response Message
DoExpressCheckoutPayment Response Fields
PAYMENTREQUEST_n_SELL
ERUSERNAME
SELLERUSERNAME
(deprecated)
xs:string
(Optional) Current name of the merchant or business at the marketplace site. This
name may be shown to the buyer. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive.
SELLERUSERNAME is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SELLERUSERNAME instead.
PAYMENTREQUEST_n_SELL
ERREGISTRATIONDATE
SELLERREGISTRATIONDAT
E (deprecated)
(Optional) Date when the merchant registered with the marketplace. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z
SELLERREGISTRATIONDATE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SELLERREGISTRATIONDATE instead.
Field Description
TOKEN The timestamped token value that was returned by SetExpressCheckout response
and passed on GetExpressCheckoutDetails request.
Character length and limitations: 20 single-byte characters
PAYMENTTYPE Information about the payment.
NOTE 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 Flag to indicate whether you need to redirect the buyer back to PayPal after
successfully completing the transaction.
If set to true, you can redirect users to the following URL with the token value
appended:
https://www.paypal.com/cgi-bin/webscr?cmd=_complete-express-
checkout&token=(token)
NOTE:Use this field only if you are using giropay or bank transfer payment methods
in Germany.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
106 August 2012 Name-Value Pair API Developer Guide
SUCCESSPAGEREDIRECT
REQUESTED
Flag to indicate whether you would like to redirect the buyer to sign up for
PayPal after completing the transaction.
If set to true, you can redirect users to the following URL with the token value
appended::
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout-
success&token=(token)
BILLINGAGREEMENTID The ID of the billing agreement associated with the Express Checkout transaction.
L_FMFfilterIDn
(deprecated)
Filter ID, including the filter type, (PENDING, REPORT, or DENY), the filter ID, and
the entry number, n, starting from 0. Filter ID 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
This field is deprecated since version 63.0. Use L_PAYMENTINFO_0_FMFfilterIDn
instead.
L_FMFfilterNAMEn
(deprecated)
Filter name, including the filter type, (PENDING, REPORT, or DENY), the filter
NAME, and the entry number, n, starting from 0.
This field is deprecated since version 63.0. Use L_PAYMENTINFO_0_FMFfilterNAMEn
instead.
PAYMENTINFO_n_SHIPP
INGAMT
SHIPPINGAMT
(deprecated)
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.
If you specify a value for PAYMENTINFO_n_SHIPPINGAMT, you must also specify a
value for PAYMENTINFO_n_ITEMAMT.
SHIPPINGAMT is deprecated since version 63.0. Use
PAYMENTINFO_n_SHIPPINGAMT instead.
Field Description
Name-Value Pair API Developer Guide August 2012 107
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
PAYMENTINFO_n_SELLE
RID
Unique, non-changing identifier for the merchant at the marketplace site. (Optional)
You can specify up to 10 payments, where ‘n’ is a digit between 0 and 9, inclusive.
Character length and limitations: 13 single-byte alphanumeric characters.
PAYMENTINFO_n_SELLE
RUSERNAME
Current name of the merchant or business at the marketplace site. This name may be
shown to the buyer.
You can specify up to 10 payments, where ‘n’ is a digit between 0 and 9, inclusive.
PAYMENTINFO_n_SELLE
RREGISTRATIONDATE
Date when the merchant registered with the marketplace.
You can specify up to 10 payments, where ‘n’ is a digit between 0 and 9, inclusive.
Character length and limitations: Date and time are in UTC/GMT format. For
example: 2011-06-24T05:38:?48Z.
PAYMENTINFO_n_PAREN
TTRANSACTIONID
PARENTTRANSACTIONID
(deprecated)
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.
PARENTTRANSACTIONID is deprecated since version 63.0. Use
PAYMENTINFO_n_PARENTTRANSACTIONID instead.
PAYMENTINFO_n_RECEI
PTID
RECEIPTID
(deprecated)
Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format.
RECEIPTID is deprecated since version 63.0. Use PAYMENTINFO_n_RECEIPTID
instead.
PAYMENTINFO_n_EXPEC
TEDECHECKCLEARDATE
EXPECTEDECHECKCLEAR
DATE
(deprecated)
eCheck latest expected clear date.
EXPECTEDECHECKCLEARDATE is deprecated since version 63.0. Use
PAYMENTINFO_n_EXPECTEDECHECKCLEARDATE instead.
PAYMENTINFO_n_SHIPP
INGMETHOD
SHIPPINGMETHOD
(deprecated)
Shipping method selected by the user during check-out.
SHIPPINGMETHOD is deprecated since version 63.0. Use
PAYMENTINFO_n_SHIPPINGMETHOD instead.
PAYMENTINFO_n_INSTR
UMENTCATEGORY
This field holds the category of the instrument only when it is promotional. Return
value 1 represents BML.
PAYMENTINFO_n_OFFER
CODE
Code used to identify the promotion offer.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
108 August 2012 Name-Value Pair API Developer Guide
Payment Information 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.
PAYMENTINFO_n_OFFER
TRACKINGID
Unique identification for merchant/buyer/offer combo.
Field Description
PAYMENTINFO_n_TRANS
ACTIONID
TRANSACTIONID
(deprecated)
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
TRANSACTIONID is deprecated since version 63.0. Use
PAYMENTINFO_n_TRANSACTIONID instead.
PAYMENTINFO_n_TRANS
ACTIONTYPE
TRANSACTIONTYPE
(deprecated)
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
TRANSACTIONTYPE is deprecated since version 63.0. Use
PAYMENTINFO_0_TRANSACTIONTYPE instead.
PAYMENTINFO_n_PAYME
NTTYPE
PAYMENTTYPE
(deprecated)
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
PAYMENTTYPE is deprecated since version 63.0. Use
PAYMENTINFO_0_PAYMENTTYPE instead.
Field Description
Name-Value Pair API Developer Guide August 2012 109
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
PAYMENTINFO_n_ORDER
TIME
ORDERTIME (deprecated)
Time/date stamp of payment.
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z
ORDERTIME is deprecated since version 63.0. Use PAYMENTINFO_0_ORDERTIME
instead.
PAYMENTINFO_n_AMT
AMT (deprecated)
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 (,).
AMT is deprecated since version 63.0. Use PAYMENTINFO_0_AMT instead.
PAYMENTINFO_n_CURRE
NCYCODE
CURRENCYCODE
(deprecated)
A 3-character currency code. Default: USD.
CURRENCYCODE is deprecated since version 63.0. Use
PAYMENTINFO_0_CURRENCYCODE instead.
PAYMENTINFO_n_FEEAM
T
FEEAMT (deprecated)
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 (,).
FEEAMT is deprecated since version 63.0. Use PAYMENTINFO_0_FEEAMT instead.
PAYMENTINFO_n_SETTL
EAMT
SETTLEAMT (deprecated)
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 (,).
SETTLEAMT is deprecated since version 63.0. Use PAYMENTINFO_0_SETTLEAMT
instead.
PAYMENTINFO_n_TAXAM
T
TAXAMT (deprecated)
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 (,).
TAXAMT is deprecated since version 63.0. Use PAYMENTINFO_0_TAXAMT instead.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
110 August 2012 Name-Value Pair API Developer Guide
PAYMENTINFO_n_EXCHA
NGERATE
EXCHANGERATE
(deprecated)
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
EXCHANGERATE is deprecated since version 63.0. Use
PAYMENTINFO_0_EXCHANGERATE instead.
PAYMENTINFO_n_PAYME
NTSTATUS
PAYMENTSTATUS
(deprecated)
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 PAYMENTINFO_n_HOLDDECISION field for more information.
See the HoldDecision field for more information.
PAYMENTSTATUS is deprecated since version 63.0. Use
PAYMENTINFO_0_PAYMENTSTATUS instead.
Field Description
Name-Value Pair API Developer Guide August 2012 111
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
PAYMENTINFO_n_PENDI
NGREASON
PENDINGREASON
(deprecated)
Reason the payment is pending. It is one of the following values:
Reason the payment is pending. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive. It is one of the following values:
-none – No pending reason.
-address – The payment is pending because your buyer did not include a
confirmed shipping address and your Payment Receiving Preferences is set such
that you want to manually accept or deny each of these payments. To change your
preference, go to the Preferences section of your Profile.
-authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
-echeck – The payment is pending because it was made by an eCheck that has not
yet cleared.
-intl – The payment is pending because you hold a non-U.S. account and do not
have a withdrawal mechanism. You must manually accept or deny this payment
from your Account Overview.
-multi-currency – You do not have a balance in the currency sent, and you do
not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this payment.
-order – The payment is pending because it is part of an order that has been
authorized but not settled.
-paymentreview – The payment is pending while it is being reviewed by PayPal
for risk.
-unilateral – The payment is pending because it was made to an email address
that is not yet registered or confirmed.
-verify – The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
-other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal customer service.
NOTE:PendingReason is returned in the response only if PaymentStatus is
Pending.
PENDINGREASON is deprecated since version 63.0. Use
PAYMENTINFO_0_PENDINGREASON instead.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
112 August 2012 Name-Value Pair API Developer Guide
PAYMENTINFO_n_REASO
NCODE
REASONCODE
(deprecated)
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.
REASONCODE is deprecated since version 63.0. Use PAYMENTINFO_0_REASONCODE
instead.
PAYMENTINFO_n_HOLDD
ECISION
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.
PAYMENTINFO_n_PROTE
CTIONELIGIBILITY
PROTECTIONELIGIBILI
TY (deprecated)
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.
PROTECTIONELIGIBILITY is deprecated since version 63.0. Use
PAYMENTINFO_0_PROTECTIONELIGIBILITY instead.
Field Description
Name-Value Pair API Developer Guide August 2012 113
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
PAYMENTINFO_n_PROTE
CTIONELIGIBILITYTYP
E
Since version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
Since version 64.4, the kind of seller protection in force for the transaction. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive. It is one of
the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for both
Unauthorized Payment and Item Not Received
-ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received
-UnauthorizedPaymentEligible – Merchant is protected by PayPal's Seller
Protection Policy for Unauthorized Payment
-Ineligible – Merchant is not protected under the Seller Protection Policy
This field is available since version 64.4.
STOREID StoreId as entered in the transaction
TERMINALID TerminalId as entered in the transaction
PAYMENTINFO_n_EBAYI
TEMAUCTIONTXNID
EBAYITEMAUCTIONTXNI
D (deprecated)
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
EBAYITEMAUCTIONTXNID is deprecated since version 63.0. Use
PAYMENTINFO_0_EBAYITEMAUCTIONTXNID instead.
PAYMENTREQUEST_n_PA
YMENTREQUESTID
PAYMENTREQUESTID
(deprecated)
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
PAYMENTREQUESTID is deprecated since version 63.0. Use
PAYMENTINFO_0_PAYMENTREQUESTID instead.
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
114 August 2012 Name-Value Pair API Developer Guide
L_PAYMENTINFO_n_FMF
filterIDm
L_FMFfilterIDn
(deprecated)
Filter ID, including the filter type, (PENDING, REPORT, or DENY), the filter ID, and
the entry number, m, starting from 0. Filter ID 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
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and
m specifies the list item within the payment.
L_FMFfilterIDn is deprecated since version 63.0. Use
L_PAYMENTINFO_n_FMFfilterIDn instead.
L_PAYMENTINFO_n_FMF
filterNAMEm
L_FMFfilterNAMEn
(deprecated)
Filter name, including the filter type, (PENDING, REPORT, or DENY), the filter NAME,
and the entry number, m, starting from 0.
Filter name, including the filter type, (PENDING, REPORT, or DENY), the filter NAME,
and the entry number, m, starting from 0. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive, and m specifies the list item within the payment.
L_FMFfilterNAMEn is deprecated since version 63.0. Use
L_PAYMENTINFO_n_FMFfilterNAMEn instead.
InstrumentDetails ns:InstrumentDetailsType
Promotional instrument information.
This field is introduced in API version 71.0.
OfferDetails ns:OfferDetailsType
Specific information for an offer.
This field is introduced in API version 71.0.
Field Description
Name-Value Pair API Developer Guide August 2012 115
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation 6
Payment Error Type Fields
UserSelectedOptions Fields
Field Description
PAYMENTREQUEST_n_SH
ORTMESSAGE
xs:string
Payment error short message. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
PAYMENTREQUEST_n_LO
NGMESSAGE
xs:string
Payment error long message. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
PAYMENTREQUEST_n_ER
RORCODE
xs:string
Payment error code. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive.
PAYMENTREQUEST_n_SE
VERITYCODE
xs:string
Payment error severity code. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
PAYMENTREQUEST_n_AC
K
xs:string
Application-specific error values indicating more about the error condition. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Field Description
SHIPPINGCALCULATIONM
ODE
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
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
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 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 The name of the shipping option, such as air or ground.
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
116 August 2012 Name-Value Pair API Developer Guide
Seller Details Type Fields
Field Description
PAYMENTREQUEST_n_SELLER
PAYPALACCOUNTID
Unique identifier for the merchant. For parallel payments, this field contains
either the Payer Id or the email address of the merchant. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 127 single-byte alphanumeric characters
PAYMENTREQUEST_n_SECURE
MERCHANTACCOUNTID
Unique PayPal customer account number (of the merchant). This field is
returned in the response. It is ignored if passed in the request.
Name-Value Pair API Developer Guide August 2012 117
7GetBalance API Operation
The GetBalance API Operation obtains the available balance for a PayPal account.
GetBalance Request Message
GetBalance Request Fields
GetBalance Response Message
GetBalance Response Fields
Field Description
METHOD (Required) Must be GetBalance.
RETURNALLCURRENCIES (Optional) Indicates whether to return all currencies. It is one of the following values:
-0 – Return only the balance for the primary currency holding.
-1 – Return the balance for each currency holding.
NOTE:This field is availalble since version 51. Prior versions return only the
balance for the primary currency holding.
Field Description
L_AMTn Available balance and associated currency code for the primary currency holding.
L_CURRENCYCODEn Currency code, such as USD, associated with the holding.
GetBalance API Operation
GetBalance Response Message
7
118 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 119
8GetPalDetails API Operation
The GetPalDetails API operation obtains your Pal ID, which is the PayPal-assigned
merchant account number, and other information about your account. You need the account
number when working with dynamic versions of PayPal buttons and logos.
GetPalDetails Request Message
GetPalDetails Request Fields
GetPalDetails Response Message
GetPalDetails Response Fields
Field Description
METHOD (Required) Must be GetPalDetails.
Field Description
PAL PayPal-assigned merchant account number.
GetPalDetails API Operation
GetPalDetails Response Message
8
120 August 2012 Name-Value Pair API Developer Guide
LOCALE Country code representing the merchant’s default locale. It is one of the following
locales:
-AU – Australia
-AT – Austria
-BE – Belgium
-BR – Brazil
-CA – Canada
-CH – Switzerland
-CN – China
-DE – Germany
-ES – Spain
-GB – United Kingdom
-FR – France
-IT – Italy
-NL – Netherlands
-PL – Poland
-PT – Portugal
-RU – Russia
-US – United States
-The following 5-character codes are also supported for languages in specific
countries:
da_DK – Danish (for Denmark only)
he_IL – Hebrew (all)
id_ID – Indonesian (for Indonesia only)
jp_JP – Japanese (for Japan only)
no_NO – Norwegian (for Norway only)
pt_BR – Brazilian Portuguese (for Portugal and Brazil only)
ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)
sv_SE – Swedish (for Sweden only)
th_TH – Thai (for Thailand only)
tr_TR – Turkish (for Turkey only)
zh_CN – Simplified Chinese (for China only)
zh_HK – Traditional Chinese (for Hong Kong only)
zh_TW – Traditional Chinese (for Taiwan only)
Character length and limitations: 2 single-byte characters
Field Description
Name-Value Pair API Developer Guide August 2012 121
9GetTransactionDetails API
Operation
The GetTransactionDetails API operation obtains information about a specific
transaction.
GetTransactionDetails Request Message
GetTransactionDetails Request Fields
GetTransactionDetails Response Message
NOTE:All fields defined in the formal structure of GetTransactionDetailsResponse
are not necessarily returned. Data are returned in a response only if PayPal has
recorded data that corresponds to the field.
GetTransactionDetails Response Fields
Field Description
METHOD Must be GetTransactionDetails.
TRANSACTIONID (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
Field Description
SHIPPINGCALCULATION
MODE
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.
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
122 August 2012 Name-Value Pair API Developer Guide
INSURANCEOPTIONSELE
CTED
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.
L_SHIPPINGOPTIONISD
EFAULTn
Default shipping option displayed on the PayPal pages. This field is required if you
specify the Callback URL. It is one of the following values:
-true – This is the default flat-rate shipping option. PayPal displays this option by
default.
-false – This flat-rate shipping option is not displayed as the default.
NOTE:There must be ONE and ONLY ONE default. It is not OK to have no default.
L_SHIPPINGOPTIONNAM
En
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.
L_SHIPPINGOPTIONAMO
UNTn
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 The gift message the buyer entered on the PayPal pages.
Limitations: 100 single-byte characters
GIFTRECEIPTENABLE 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 Label for the gift wrap option such as “Blue box with ribbon”.
Limitations: 25 single-byte characters
GIFTWRAPAMOUNT 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 (,).
BUYERMARKETINGEMAIL The email address the buyer entered on the PayPal pages to be notified of promotions
or special events.
Limitations: 127 single-byte characters
SURVEYQUESTION 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
Field Description
Name-Value Pair API Developer Guide August 2012 123
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
Receiver Information Fields
Payer Information Fields
SURVEYCHOICESELECTE
D
Survey response the buyer selected on the PayPal pages.
Limitations: 15 single-byte characters
Field Description
RECEIVERBUSINESS Details about a single transaction. This field is not application for point-of-sale
transactions.
RECEIVEREMAIL 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 Unique account ID of the payment recipient (the merchant). This value is the same as
the value of the recipient's referral ID.
Field Description
EMAIL Email address of buyer.
Character length and limitations: 127 single-byte characters
PAYERID Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters
PAYERSTATUS Status of buyer. It is one of the following values:
-verified
-unverified
Character length and limitations: 10 single-byte alphabetic characters
COUNTRYCODE 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 Buyer’s business name.
Character length and limitations: 127 single-byte characters
Field Description
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
124 August 2012 Name-Value Pair API Developer Guide
Payer Name Fields
Address Fields
Field Description
SALUTATION Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FIRSTNAME Buyer’s first name.
Character length and limitations: 25 single-byte characters
MIDDLENAME Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LASTNAME Buyer’s last name.
Character length and limitations: 25 single-byte characters
SUFFIX Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
ADDRESSOWNER eBay company that maintains this address. It is one of the following values:
-eBay
-PayPal
ADDRESSSTATUS Status of street address on file with PayPal. It is one of the following values:
-none
-Confirmed
-Unconfirmed
SHIPTONAME Person’s name associated with this address.
Character length and limitations: 32 single-byte characters
SHIPTOSTREET First street address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 Second street address.
Character length and limitations: 100 single-byte characters
SHIPTOCITY Name of city.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters
SHIPTOZIP U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Name-Value Pair API Developer Guide August 2012 125
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
Payment Information Fields
SHIPTOCOUNTRYCODE Country code.
Character length and limitations: 2 single-byte characters
SHIPTOPHONENUM Phone number.
Character length and limitations: 20 single-byte characters
Field Description
TRANSACTIONID Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters
PARENTTRANSACTIONID 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 Receipt identification number
Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format
TRANSACTIONTYPE The type of transaction. It is one of the following values:
-cart
-express-checkout
Character length and limitations:15 single-byte characters
PAYMENTTYPE 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
ORDERTIME Time/date stamp of payment,
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z
Field Description
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
126 August 2012 Name-Value Pair API Developer Guide
AMT 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 (,).
CURRENCYCODE A 3-character currency code.
FEEAMT 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 (,).
SETTLEAMT 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 (,).
TAXAMT Tax charged on the transaction.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
EXCHANGERATE Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency. If the buyer chooses to pay with a currency other than the
non-primary currency, the conversion occurs in the buyer’s account.
Character length and limitations: Decimal value that does not exceed 17 characters,
including decimal point
Field Description
Name-Value Pair API Developer Guide August 2012 127
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
PAYMENTSTATUS Status of the payment. It is one of the following values:
-None – No status
-Canceled-Reversal– A reversal has been canceled, for example, when you
win a dispute and the funds for the reversal have been returned to you.
-Completed – The payment has been completed, and the funds have been added
successfully to your account balance.
-Denied – You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the
PendingReason element.
-Expired – The authorization period for this payment has been reached.
-Failed – The payment has failed. This happens only if the payment was made
from your buyer’s bank account.
-In-Progress – The transaction has not terminated, for example, an
authorization may be awaiting completion.
-Partially-Refunded – The payment has been partially refunded.
-Pending – The payment is pending. See the PendingReason field for more
information.
-Refunded – You refunded the payment.
-Reversed – A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer. The reason for the reversal is specified in the ReasonCode element.
-Processed – A payment has been accepted.
-Voided – An authorization for this transaction has been voided.
Field Description
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
128 August 2012 Name-Value Pair API Developer Guide
PENDINGREASON The reason the payment is pending. It is one of the following values:
-none – No pending reason.
-address – The payment is pending because your buyer did not include a
confirmed shipping address and your Payment Receiving Preferences is set such
that you want to manually accept or deny each of these payments. To change your
preference, go to the Preferences section of your Profile.
-authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
-echeck – The payment is pending because it was made by an eCheck that has not
yet cleared.
-intl – The payment is pending because you hold a non-U.S. account and do not
have a withdrawal mechanism. You must manually accept or deny this payment
from your Account Overview.
-multi-currency – You do not have a balance in the currency sent, and you do
not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this payment.
-order – The payment is pending because it is part of an order that has been
authorized but not settled.
-paymentreview – The payment is pending while it is being reviewed by PayPal
for risk.
-unilateral – The payment is pending because it was made to an email address
that is not yet registered or confirmed.
-verify –The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
-other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal Customer Service.
NOTE:PendingReason is returned in the response only if PaymentStatus is
Pending.
REASONCODE The reason for a reversal if the transaction type is reversal. It is one of the following
values:
-none – No reason code.
-chargeback – A reversal has occurred on this transaction due to a chargeback by
your buyer.
-guarantee – A reversal has occurred on this transaction due to your buyer
triggering a money-back guarantee.
-buyer-complaint – A reversal has occurred on this transaction due to a
complaint about the transaction from your buyer.
-refund – A reversal has occurred on this transaction because you have given the
buyer a refund.
-other – A reversal has occurred on this transaction due to a reason not listed
above.
Field Description
Name-Value Pair API Developer Guide August 2012 129
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
Payment Item Information Fields
PROTECTIONELIGIBILI
TY
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
Since version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for both
Unauthorized Payment and Item Not Received.
-ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received.
-UnauthorizedPaymentEligible – Merchant is protected by PayPal's Seller
Protection Policy for Unauthorized Payment.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
This field is introduced in API version 64.4.
STOREID xs:string
StoreId as entered in the transaction.
TERMINALID xs:string
TerminalId as entered in the transaction.
Field Description
INVNUM Invoice number you set in the original transaction.
Character length and limitations: 256 single-byte alphanumeric characters
CUSTOM Custom field you set in the original transaction.
Character length and limitations: 127 single-byte alphanumeric characters
NOTE Memo entered by your customer in PayPal Website Payments note field.
Character length and limitations: 255 single-byte alphanumeric characters
SALESTAX Amount of tax charged on payment.
Field Description
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
130 August 2012 Name-Value Pair API Developer Guide
Payment Item Fields
Field Description
EbayItemTxnId
L_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
L_DESCnItem name set by you or entered by the customer.
NOTE:Character length and limitations: 127 single-byte alphanumeric characters.
These parameters must be ordered sequentially beginning with 0 (for example
L_DESC0, L_DESC1).
L_NUMBERnItem 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
These parameters must be ordered sequentially beginning with 0 (for example
L_NUMBER0, L_NUMBER1).
L_QTYnQuantity set by you or entered by the buyer.
Character length and limitations: no limit
CouponID
L_COUPONIDn
xs:string
(Optional) Coupon identification number.
CouponAmount
L_COUPONAMOUNTn
xs:string
(Optional) Amount (value) of the coupon.
CouponAmountCurrenc
y
L_COUPONAMOUNTCURRE
NCYn
xs:string
(Optional) Currency of the coupon amount, e.g., a 3-character currency code.
LoyaltyCardDiscount
Amount
L_LOYALTYCARDDISCOU
NTAMOUNTn
xs:string
(Optional) Amount of discount associated with this Loyalty Card incentive.
NOTE:Use character string as shown.
LoyaltyCardDiscount
Currency
L_LOYALTYCARDISCOUN
TCURRENCYn
xs:string
(Optional) Currency of the loyalty card discount, for example, a 3-character currency
code.
NOTE:Use character string as shown.
L_AMTnCost of item.
These parameters must be ordered sequentially beginning with 0 (for example
L_AMT0, L_AMT1).
Name-Value Pair API Developer Guide August 2012 131
GetTransactionDetails API Operation
GetTransactionDetails Response Message 9
Auction Information Fields
Subscription Terms Fields
L_OPTIONSNAMEnPayPal option names for an item in the shopping cart; each name corresponds to an
option value. There can be multiple option names per item.
The option names are ordered sequentially beginning with 0 (for example,
L_OPTIONSNAMES0, L_OPTIONSNAME1).
L_OPTIONSVALUEnPayPal option values corresponding to option names of an item in the shopping cart.
The option names are ordered sequentially beginning with 0 (for example,
L_OPTIONSVALUE0, L_OPTIONSVALUE1).
Field Description
BUYERID Buyer’s auction ID.
CLOSINGDATE Auction’s close date.
MULTIITEM Counter used for multi-item auction payments.
Field Description
AMOUNT Amount subscriber is to be charged in 1 payment.
Character length and limitations: No limit
PERIOD Period of time that the subscriber is charged.
Character length and limitations: No limit
Field Description
GetTransactionDetails API Operation
GetTransactionDetails Response Message
9
132 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 133
10 ManagePendingTransactionStatus
API Operation
The ManagePendingTransactionStatus API operation accepts or denys a pending transaction
held by Fraud Management Filters.
ManagePendingTransactionStatus Request Message
ManagePendingTransactionStatus Request Fields
Field Description
METHOD (Required) Must be ManagePendingTransactionStatus.
TRANSACTIONID (Required) The transaction ID of the payment transaction.
ACTION (Required) The operation you want to perform on the transaction. It is one of the
following values:
-Accept – Accepts the payment
-Deny – Rejects the payment
ManagePendingTransactionStatus API Operation
ManagePendingTransactionStatus Response Message
10
134 August 2012 Name-Value Pair API Developer Guide
ManagePendingTransactionStatus Response Message
ManagePendingTransactionStatus Response Fields
Field Description
TRANSACTIONID The transaction ID of the transaction whose payment has been denied or accepted.
STATUS Displays in the following message:
“The Status of the transaction after running your action (accept/deny) is
TransactionStatus.”
TransactionStatus is one of the following values:
-Pending
-Processing
-Completed
-Denied
-Reversed
-Display Only
-Partially Refunded
-Created Refunded
Name-Value Pair API Developer Guide August 2012 135
11 MassPay API Operation
The MassPay API operation makes a payment to one or more PayPal account holders.
MassPay Request Message
MassPay Request Fields
MassPay Response Message
MassPay Response Fields
The fields in the response are the standard response header fields.
Field Description
METHOD (Required) Must be MassPay.
EMAILSUBJECT (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
CURRENCYCODE Currency code.
Character length and limitations: 3 single-byte characters
RECEIVERTYPE (Optional) How you identify the recipients of payments in this call to MassPay. It is
one of the following values:
-EmailAddress
-UserID
-PhoneNumber
MassPay API Operation
MassPay Response Message
11
136 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 137
12 Recurring Payments and
Reference Transactions API
Operations
The PayPal API includes the following API operations supporting recurring payments and
reference transactions:
CreateRecurringPaymentsProfile API Operation
The CreateRecurringPaymentsProfile API operation creates a recurring payments
profile.
You must invoke the CreateRecurringPaymentsProfile API operation for each profile
you want to create. The API operation creates a profile and an associated billing agreement.
NOTE:There is a one-to-one correspondence between billing agreements and recurring
payments profiles. To associate a recurring payments profile with its billing
agreement, you must ensure that the description in the recurring payments profile
matches the description of a billing agreement. For version 54.0 and later, use
SetExpressCheckout to initiate creation of a billing agreement.
CreateRecurringPaymentsProfile Request Message
CreateRecurringPaymentsProfile Request Fields
Field Description
METHOD (Required) Must be CreateRecurringPaymentsProfile.
TOKEN A timestamped token, the value of which was returned in the response to the first call
to SetExpressCheckout. You can also use the token returned in the
SetCustomerBillingAgreement response. Either this token or a credit card
number is required. If you include both token and credit card number, the token is
used and credit card number is ignored Call CreateRecurringPaymentsProfile
once for each billing agreement included in SetExpressCheckout request and use
the same token for each call. Each CreateRecurringPaymentsProfile request
creates a single recurring payments profile.
NOTE:Tokens expire after approximately 3 hours.
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
138 August 2012 Name-Value Pair API Developer Guide
Recurring Payments Profile Details Fields
Schedule Details Fields
Field Description
SUBSCRIBERNAME (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
PROFILESTARTDATE (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 (Optional) The merchant’s own unique reference or invoice number.
Character length and limitations: 127 single-byte alphanumeric characters
Field Description
DESC (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
MAXFAILEDPAYMENTS (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
AUTOBILLOUTAMT (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.
Name-Value Pair API Developer Guide August 2012 139
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
Billing Period Details Fields
Field Description
BILLINGPERIOD (Required) Unit for billing during this subscription period. It is one of the following
values:
-Day
-Week
-SemiMonth
-Month
-Year
For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE:The combination of BillingPeriod and BillingFrequency cannot
exceed one year.
BILLINGFREQUENCY (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.
TOTALBILLINGCYCLES (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.
AMT (Required) Billing amount for each billing cycle during this payment period. This
amount does not include shipping and tax amounts.
NOTE:All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TRIALBILLINGPERIOD Unit for billing during this subscription period; required if you specify an optional
trial period. It is one of the following values:
-Day
-Week
-SemiMonth
-Month
-Year
For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE:The combination of BillingPeriod and BillingFrequency cannot
exceed one year.
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
140 August 2012 Name-Value Pair API Developer Guide
TRIALBILLINGFREQUEN
CY
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.
TRIALTOTALBILLINGCY
CLES
(Optional) Number of billing cycles for trial payment period.
TRIALAMT Billing amount for each billing cycle during this payment period; required if you
specify an optional trial period. This amount does not include shipping and tax
amounts.
NOTE:All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
CURRENCYCODE (Required) Currency code (default is USD).
Character length and limitations: 3 single-byte characters
SHIPPINGAMT (Optional) Shipping amount for each billing cycle during this payment period.
NOTE:All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TAXAMT (Optional) Taxamount for each billing cycle during this payment period.
NOTE:All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
Name-Value Pair API Developer Guide August 2012 141
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
Actvation Details Fields
Ship To Address Fields
Field Description
INITAMT (Optional) Initial non-recurring payment amount due immediately upon profile
creation. Use an initial amount for enrolment or set-up fees.
NOTE:All amounts included in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
FAILEDINITAMTACTION (Optional) Action you can specify when a payment fails. It is one of the following
values:
-ContinueOnFailure – By default, PayPal suspends the pending profile in the
event that the initial payment amount fails. You can override this default behavior
by setting this field to ContinueOnFailure. Then, if the initial payment amount
fails, PayPal adds the failed payment amount to the outstanding balance for this
recurring payment profile.
When you specify ContinueOnFailure, a success code is returned to you in the
CreateRecurringPaymentsProfile response and the recurring payments
profile is activated for scheduled billing immediately. You should check your IPN
messages or PayPal account for updates of the payment status.
-CancelOnFailure – If this field is not set or you set it to CancelOnFailure,
PayPal creates the recurring payment profile, but places it into a pending status
until the initial payment completes. If the initial payment clears, PayPal notifies
you by IPN that the pending profile has been activated. If the payment fails,
PayPal notifies you by IPN that the pending profile has been canceled.
Field Description
SHIPTONAME Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
SHIPTOSTREET First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 (Optional) Second street address.
Character length and limitations: 100 single-byte characters
SHIPTOCITY Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
142 August 2012 Name-Value Pair API Developer Guide
Credit Card Details Fields
SHIPTOZIP 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
SHIPTOCOUNTRY Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
SHIPTOPHONENUM (Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
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 CURRENCYCODE to GBP. In
addition, you must specify either STARTDATE or ISSUENUMBER.
Character length and limitations: Up to 10 single-byte alphabetic characters
ACCT (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.
EXPDATE Credit card expiration date. This field is required if you are using recurring payments
with direct payments.
Character length and limitations: 6 single-byte alphanumeric characters, including
leading zero, in the format MMYYYY
CVV2 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.
STARTDATE (Optional) Month and year that Maestro card was issued.
Character length and limitations: Must be 6 digits, including leading zero, in the
format MMYYYY
ISSUENUMBER (Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum
Field Description
Name-Value Pair API Developer Guide August 2012 143
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
Payer Information Fields
Payer Name Fields
Address Fields
Field Description
EMAIL (Required) Email address of buyer.
Character length and limitations: 127 single-byte characters
PAYERID (Optional) Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters
PAYERSTATUS (Optional) Status of buyer. It is one of the following values:
-verified
-unverified
Character length and limitations: 10 single-byte alphabetic characters
COUNTRYCODE (Optional) Buyer’s country of residence in the form of ISO standard 3166 two-
character country codes.
Character length and limitations: 2 single-byte characters
BUSINESS (Optional) Buyer’s business name.
Character length and limitations: 127 single-byte characters
Field Description
SALUTATION (Optional) Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FIRSTNAME (Optional) Buyer’s first name.
Character length and limitations: 25 single-byte characters
MIDDLENAME (Optional) Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LASTNAME (Optional) Buyer’s last name.
Character length and limitations: 25 single-byte characters
SUFFIX (Optional) Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
STREET (Required) First street address.
Character length and limitations: 100 single-byte characters
STREET2 (Optional) Second street address.
Character length and limitations: 100 single-byte characters
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
12
144 August 2012 Name-Value Pair API Developer Guide
Payment Details Item Fields
CITY (Required) Name of city.
Character length and limitations: 40 single-byte characters
STATE (Required) State or province.
Character length and limitations: 40 single-byte characters
COUNTRYCODE (Required) Country code.
Character length and limitationst: 2 single-byte characters
ZIP (Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM (Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
L_PAYMENTREQUEST_n_IT
EMCATEGORYm
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. These parameters must be ordered sequentially beginning with 0 (for
example L_PAYMENTREQUEST_n_ITEMCATEGORY0,
L_PAYMENTREQUEST_n_ITEMCATEGORY1). Is one of the following values:
-Digital
-Physical
This field is introduced in version 69.0.
L_PAYMENTREQUEST_n_NA
MEm
Item name. This field is required when ItemCategory is passed.
Item name. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.
L_PAYMENTREQUEST_n_DE
SCm
(Optional) Item description. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_DESC0,
L_PAYMENTREQUEST_n_DESC1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.
Field Description
Name-Value Pair API Developer Guide August 2012 145
Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation 12
CreateRecurringPaymentsProfile Response Message
CreateRecurringPaymentsProfile Response Fields
L_PAYMENTREQUEST_n_AM
Tm
Cost of item. This field is required when ItemCategory is passed.
Cost of item. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).
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.
L_PAYMENTREQUEST_n_NU
MBERm
(Optional) Item number. These parameters must be ordered sequentially beginning
with 0 (for example L_PAYMENTREQUEST_n_NUMBER0,
L_PAYMENTREQUEST_n_NUMBER1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.
L_PAYMENTREQUEST_n_QT
Ym
Item quantity. This field is required when ItemCategory is passed.
Item quantity. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).
Character length and limitations: Any positive integer
This field is introduced in version 69.0.
L_PAYMENTREQUEST_n_TA
XAMTm
(Optional) Item sales tax. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_TAXAMT0,
L_PAYMENTREQUEST_n_TAXAMT1).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 69.0.
Field Description
PROFILEID A unique identifier for future reference to the details of this recurring payment.
Character length and limitations: Up to 14 single-byte alphanumeric characters.
Field Description
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
12
146 August 2012 Name-Value Pair API Developer Guide
GetRecurringPaymentsProfileDetails API Operation
The GetRecurringPaymentsProfileDetails API operation obtains information about a
recurring payments profile.
GetRecurringPaymentsProfileDetails Request Message
GetRecurringPaymentsProfileDetails Request Fields
GetRecurringPaymentsProfileDetails Response Message
GetRecurringPaymentsProfileDetails Response Fields
PROFILESTATUS Status of the recurring payment profile.
-ActiveProfile – The recurring payment profile has been successfully created
and activated for scheduled payments according the billing instructions from the
recurring payments profile.
-PendingProfile – The system is in the process of creating the recurring
payment profile. Please check your IPN messages for an update.
Field Description
METHOD (Required) Must be GetRecurringPaymentsProfileDetails.
PROFILEID (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
Field Description
PROFILEID Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
STATUS Status of the recurring payment profile. It is one of the following values:
-Active
-Pending
-Cancelled
-Suspended
-Expired
Field Description
Name-Value Pair API Developer Guide August 2012 147
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation 12
Recurring Payments Profile Details Fields
DESC Description of the recurring payment.
Character length and limitations: 127 single-byte alphanumeric characters
AUTOBILLOUTAMT 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 Number of scheduled payments that can fail before the profile is automatically
suspended.
Character length and limitations: Number string representing an integer
AGGREGATEAMOUNT 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
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 Final scheduled payment due date before the profile expires.
Field Description
SUBSCRIBERNAME 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.
PROFILESTARTDATE The date when billing for this profile begins.
Must be a valid date, in UTC/GMT format.
NOTE:The profile may take up to 24 hours for activation.
PROFILEREFERENCE The merchant’s own unique reference or invoice number.
Character length and limitations: 127 single-byte alphanumeric characters.
Field Description
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
12
148 August 2012 Name-Value Pair API Developer Guide
Ship To AddressType Fields
Billing Period Details Fields
Field Description
ADDRESSSTATUS Status of street address on file with PayPal. It is one of the following values:
-none
-Confirmed
-Unconfirmed
SHIPTONAME Person’s name associated with this address.
Character length and limitations: 32 single-byte characters
SHIPTOSTREET First street address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 Second street address.
Character length and limitations: 100 single-byte characters
SHIPTOCITY Name of city.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters
SHIPTOZIP U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
SHIPTOCOUNTRYCODE Country code.
Character length and limitations: 2 single-byte characters
Field Description
BILLINGPERIOD Unit for billing during this subscription period. It is one of the following values:
-Day
-Week
-SemiMonth
-Month
-Year
For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE:The combination of BillingPeriod and BillingFrequency cannot
exceed one year.
Name-Value Pair API Developer Guide August 2012 149
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation 12
REGULARBILLINGPERIO
D
Unit for billing during this regular subscription period. It is one of the following
values:
-Day
-Week
-SemiMonth
-Month
-Year
For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE:The combination of RegularBillingPeriod and
RegularBillingFrequency cannot exceed one year.
This field is available since version 53.0.
BILLINGFREQUENCY 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.
REGULARBILLINGFREQU
ENCY
Number of billing periods that make up one regular 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.
This field is available since version 53.0.
TOTALBILLINGCYCLES 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.
REGULARTOTALBILLING
CYCLES
Number of billing cycles for the regular 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 RegularTotalBillingCycles cycles.
This field is available since version 53.0.
Field Description
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
12
150 August 2012 Name-Value Pair API Developer Guide
AMT Billing amount for each billing cycle during this payment period. This amount does
not include shipping and tax amounts.
NOTE:All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
REGULARAMT Billing amount for each billing cycle during this regular payment period. This amount
does not include shipping and tax amounts.
NOTE:All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
This field is available since version 53.0.
SHIPPINGAMT Shipping amount for each billing cycle during this payment period.
NOTE:All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
REGULARSHIPPINGAMT Shipping amount for each billing cycle during this regular payment period.
NOTE:All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
This field is available since version 53.0.
TAXAMT Tax amount for each billing cycle during this payment period.
NOTE:All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
Name-Value Pair API Developer Guide August 2012 151
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation 12
Recurring Payments Summary Details Fields
REGULARTAXAMT Tax amount for each billing cycle during this regular payment period.
NOTE:All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
This field is available since version 53.0.
CURRENCYCODE (Required) Currency code (default is USD).
Character length and limitations: 3 single-byte characters
REGULARCURRENCYCODE (Required) Currency code (default is USD).
This field is available since version 53.0.
Field Description
NEXTBILLINGDATE The next scheduled billing date, in YYYY-MM-DD format.
NUMCYCYLESCOMPLETED 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.
NUMCYCLESREMAINING The number of billing cycles remaining in the current active subscription period.
OUTSTANDINGBALANCE 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 The total number of failed billing cycles for this profile.
LASTPAYMENTDATE The date of the last successful payment received for this profile, in YYYY-MM-DD
format.
LASTPAYMENTAMT The amount of the last successful payment received for this profile.
Character length and limitations: Does not exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency, decimal separator is a period (.), and the
optional thousands separator is a comma (,). Equivalent to nine characters maximum
for USD.
Field Description
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
12
152 August 2012 Name-Value Pair API Developer Guide
Credit Card Details Fields
Payer Info Fields
Field Description
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
ACCT 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.
EXPDATE Credit card expiration date. This field is required if you are using recurring payments
with direct payments.
Character length and limitations: 6 single-byte alphanumeric characters, including
leading zero, in the format MMYYYY
STARTDATE Month and year that Maestro card was issued.
Character length and limitations: Must be 6 digits, including leading zero, in the
format MMYYYY
ISSUENUMBER Issue number of Maestro card.
Character length and limitations: 2 numeric digits
Field Description
EMAIL Email address of buyer.
Character length and limitations: 127 single-byte characters
FIRSTNAME Buyer’s first name.
Character length and limitations: 25 single-byte characters
LASTNAME Buyer’s last name.
Character length and limitations: 25 single-byte characters
Name-Value Pair API Developer Guide August 2012 153
Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation 12
Address Fields
Field Description
ADDRESSOWNER eBay company that maintains this address. It is one of the following values:
-eBay
-PayPal
ADDRESSSTATUS Status of street address on file with PayPal. It is one of the following values:
-none
-Confirmed
-Unconfirmed
SHIPTONAME Person’s name associated with this address.
Character length and limitations: 32 single-byte characters
SHIPTOSTREET First street address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 Second street address.
Character length and limitations: 100 single-byte characters
SHIPTOCITY Name of city.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters
SHIPTOZIP U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
SHIPTOCOUNTRYCODE Country code.
Character length and limitations: 2 single-byte characters
SHIPTOPHONENUM Phone number.
Character length and limitations: 20 single-byte characters
Recurring Payments and Reference Transactions API Operations
ManageRecurringPaymentsProfileStatus API Operation
12
154 August 2012 Name-Value Pair API Developer Guide
ManageRecurringPaymentsProfileStatus API Operation
The ManageRecurringPaymentsProfileStatus API operation cancels, suspends, or
reactivates a recurring payments profile.
ManageRecurringPaymentsProfileStatus Request Message
ManageRecurringPaymentsProfileStatus Request Fields
ManageRecurringPaymentsProfileStatus Response Message
ManageRecurringPaymentsProfileStatus Response Fields
Field Description
METHOD (Required) Must be ManageRecurringPaymentsProfileStatus.
PROFILEID (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 (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 (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.
Field Description
PROFILEID 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.
Name-Value Pair API Developer Guide August 2012 155
Recurring Payments and Reference Transactions API Operations
BillOutstandingAmount API Operation 12
BillOutstandingAmount API Operation
The BillOutstandingAmount API operation bills the buyer for the outstanding balance
associated with a recurring payments profile.
BillOutstandingAmount Request Message
BillOutstandingAmount Request Fields
BillOutstandingAmount Response Message
BillOutstandingAmount Response Fields
Field Description
METHOD (Required) Must be BillOutstandingAmount.
PROFILEID (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.
AMT (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 (Optional) The reason for the non-scheduled payment. For profiles created using
Express Checkout, this message is included in the email notification to the buyer for
the non-scheduled payment transaction, and can also be seen by both you and the
buyer on the Status History page of the PayPal account.
Field Description
PROFILEID 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.
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation
12
156 August 2012 Name-Value Pair API Developer Guide
UpdateRecurringPaymentsProfile API Operation
The UpdateRecurringPaymentsProfile API operation updates a recurring payments profile.
UpdateRecurringPaymentsProfile Request Message
UpdateRecurringPaymentsProfile Request Fields
Field Description
METHOD (Required) Must be UpdateRecurringPaymentsProfile.
PROFILEID (Required) Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.
Character length and limitations: 14 single-byte alphanumeric characters. 19
character profile IDs are supported for compatibility with previous versions of the
PayPal API.
NOTE (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.
DESC (Optional) Description of the recurring payment.
Character length and limitations: 127 single-byte alphanumeric characters
SUBSCRIBERNAME (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
PROFILEREFERENCE (Optional) The merchant’s own unique reference or invoice number.
Character length and limitations: 127 single-byte alphanumeric characters
ADDITIONALBILLINGCY
CLES
(Optional) The number of additional billing cycles to add to this profile.
AMT (Optional) Billing amount for each cycle in the subscription period, not including
shipping and tax amounts.
NOTE:For recurring payments with Express Checkout, the payment amount can be
increased by no more than 20% every 180 days (starting when the profile is
created).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Name-Value Pair API Developer Guide August 2012 157
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation 12
Ship To Address Fields
SHIPPINGAMT (Optional) Shipping amount for each billing cycle during the regular payment period.
NOTE:All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TAXAMT (Optional) Tax amount for each billing cycle during the regular payment period.
NOTE:All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
OUTSTANDINGAMT (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 (,).
AUTOBILLOUTAMT (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
MAXFAILEDPAYMENTS (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
PROFILESTARTDATE (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
Field Description
SHIPTONAME Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
SHIPTOSTREET First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
Field Description
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation
12
158 August 2012 Name-Value Pair API Developer Guide
Billing Period Details Fields
SHIPTOSTREET2 (Optional) Second street address.
Character length and limitations: 100 single-byte characters
SHIPTOCITY Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOZIP 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
SHIPTOCOUNTRY Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
SHIPTOPHONENUM (Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
TOTALBILLINGCYCLES (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.
AMT (Required) Billing amount for each billing cycle during this payment period. This
amount does not include shipping and tax amounts.
NOTE:All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TRIALTOTALBILLINGCY
CLES
(Optional) Number of billing cycles for trial payment period.
Field Description
Name-Value Pair API Developer Guide August 2012 159
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation 12
Credit Card Details Fields
TRIALAMT Billing amount for each billing cycle during this payment period; required if you
specify an optional trial period. This amount does not include shipping and tax
amounts.
NOTE:All amounts in the CreateRecurringPaymentsProfile request must
have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
CURRENCYCODE (Required) Currency code (default is USD).
Character length and limitations: 3 single-byte characters
SHIPPINGAMT (Optional) Shipping amount for each billing cycle during this payment period.
NOTE:All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TAXAMT (Optional) Tax amount for each billing cycle during this payment period.
NOTE:All amounts in the request must have the same currency.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
CREDITCARDTYPE (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 CURRENCYCODE to GBP. In
addition, you must specify either STARTDATE or ISSUENUMBER.
Character length and limitations: Up to 10 single-byte alphabetic characters
Field Description
Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation
12
160 August 2012 Name-Value Pair API Developer Guide
Payer Information Fields
Address Fields
ACCT (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.
EXPDATE Credit card expiration date. This field is required if you are using recurring payments
with direct payments.
Character length and limitations: 6 single-byte alphanumeric characters, including
leading zero, in the format MMYYYY
CVV2 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.
STARTDATE (Optional) Month and year that Maestro card was issued.
Character length and limitations: Must be 6 digits, including leading zero, in the
format MMYYYY
ISSUENUMBER (Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum
Field Description
EMAIL (Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters
FIRSTNAME (Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters
LASTNAME (Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Field Description
STREET (Required) First street address.
Character length and limitations: 100 single-byte characters
STREET2 (Optional) Second street address.
Character length and limitations: 100 single-byte characters
CITY (Required) Name of city.
Character length and limitations: 40 single-byte characters
Field Description
Name-Value Pair API Developer Guide August 2012 161
Recurring Payments and Reference Transactions API Operations
CreateBillingAgreement API Operation 12
UpdateRecurringPaymentsProfile Response Message
UpdateRecurringPaymentsProfile Response Fields
CreateBillingAgreement API Operation
The CreateBillingAgreement API operation creates a billing agreement with a PayPal
account holder. CreateBillingAgreement is only valid for reference transactions.
CreateBillingAgreement Request Message
CreateBillingAgreement Request Fields
STATE (Required) State or province.
Character length and limitations: 40 single-byte characters
COUNTRYCODE (Required) Country code.
Character length and limitationst: 2 single-byte characters
ZIP (Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM (Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
PROFILEID Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response. An error is returned if the profile
specified in the BillOutstandingAmount request has a status of canceled or
expired.
Field Description
METHOD (Required) Must be CreateBillingAgreement.
TOKEN (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
Field Description
Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation
12
162 August 2012 Name-Value Pair API Developer Guide
CreateBillingAgreement API Response Message
CreateBillingAgreement Response Fields
SetCustomerBillingAgreement API Operation
The SetCustomerBillingAgreement API operation initiates the creation of a billing
agreement.
NOTE:If you are using Express Checkout with version 54.0 or later of the API, do not use the
SetCustomerBillingAgreement API operation to set up a billing agreement. Use
the SetExpressCheckout API operation instead.
SetCustomerBillingAgreement Request Message
SetCustomerBillingAgreement Request Fields
Field Description
BILLINGAGREEMENTID Identification number of the billing agreement.
Field Description
METHOD (Required) Must be SetCustomerBillingAgreement.
RETURNURL (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 (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
Name-Value Pair API Developer Guide August 2012 163
Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation 12
LOCALECODE (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 (Optional) Sets the Custom Payment Page Style for payment pages associated with
this button/link. This value corresponds to the HTML variable page_style for
customizing payment pages. The value is the same as the Page Style Name you chose
when adding or editing the page style in your PayPal account.
Character length and limitations: 30 single-byte alphabetic characters
Field Description
Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation
12
164 August 2012 Name-Value Pair API Developer Guide
BillingAgreementDetails Fields
HDRIMG (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
HDRBORDERCOLOR (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
HDRBACKCOLOR (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
PAYFLOWCOLOR (Optional) Sets the background color for the payment page.
Character length and limitation: 6-character HTML hexadecimal color code in ASCII
EMAIL (Optional) Email address of the buyer as entered during checkout. PayPal uses this
value to pre-fill the PayPal membership sign-up portion of the PayPal login page.
Character length and limit: 127 single-byte alphanumeric characters
Field Description
L_BILLINGTYPEn(Required) Type of billing agreement. For recurring payments, this field must be set
to RecurringPayments. In this case, you can specify up to ten billing agreements.
Other defined values are not valid.
Type of billing agreement for reference transactions. You must have permission from
PayPal to use this field. This field must be set to one of the following values:
-MerchantInitiatedBilling - PayPal creates a billing agreement for each
transaction associated with buyer. You must specify version 54.0 or higher to use
this option.
-MerchantInitiatedBillingSingleAgreement - PayPal creates a single
billing agreement for all transactions associated with buyer. Use this value unless
you need per-transaction billing agreements. You must specify version 58.0 or
higher to use this option.
Field Description
Name-Value Pair API Developer Guide August 2012 165
Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation 12
SetCustomerBillingAgreement Response Message
SetCustomerBillingAgreement Response Fields
BILLINGTYPE Type of billing agreement for reference transactions. You must have permission from
PayPal to use this field.
For reference transactions, 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.
Other defined values are not valid.
L_BILLINGAGREEMENTD
ESCRIPTIONn
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
L_PAYMENTTYPEn(Optional) Type of PayPal payment you require for the billing agreement. It is one of
the following values:
-Any
-InstantOnly
NOTE:For recurring payments, this field is ignored.
L_BILLINGAGREEMENTC
USTOMn
(Optional) Custom annotation field for your own use.
NOTE:For recurring payments, this field is ignored.
Character length and limitations: 256 single-byte alphanumeric bytes
Field Description
TOKEN A unique time-stamped token, which uniquely identifies this transaction in
subsequent API calls.
NOTE:The token expires after 3 hours.
Character length and limitations: 20 single-byte characters
Field Description
Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation
12
166 August 2012 Name-Value Pair API Developer Guide
GetBillingAgreementCustomerDetails API Operation
The GetBillingAgreementCustomerDetails API operation obtains information about a billing
agreement’s PayPal account holder.
GetBillingAgreementCustomerDetails Request Message
GetBillingAgreementCustomerDetails Request Fields
GetBillingAgreementCustomerDetails Response Message
Payer Information Fields
Field Description
METHOD (Required) Must be GetBillingAgreementCustomerDetails.
TOKEN (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
Field Description
EMAIL Email address of buyer.
Character length and limitations: 127 single-byte characters
PAYERID Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters
PAYERSTATUS Status of buyer. It is one of the following values:
-verified
-unverified
Character length and limitations: 10 single-byte alphabetic characters
COUNTRYCODE 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 Buyer’s business name.
Character length and limitations: 127 single-byte characters
Name-Value Pair API Developer Guide August 2012 167
Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation 12
PayerNameType Fields
Address Fields
Field Description
SALUTATION Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FIRSTNAME Buyer’s first name.
Character length and limitations: 25 single-byte characters
MIDDLENAME Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LASTNAME Buyer’s last name.
Character length and limitations: 25 single-byte characters
SUFFIX Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
ADDRESSSTATUS Status of street address on file with PayPal. It is one of the following values:
-none
-Confirmed
-Unconfirmed
SHIPTONAME Person’s name associated with this address.
Character length and limitations: 32 single-byte characters
SHIPTOSTREET First street address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 Second street address.
Character length and limitations: 100 single-byte characters
SHIPTOCITY Name of city.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE State or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters
SHIPTOZIP U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
SHIPTOCOUNTRYCODE Country code.
Character length and limitations: 2 single-byte characters
Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation
12
168 August 2012 Name-Value Pair API Developer Guide
BAUpdate API Operation
The BAUpdate API operation updates or deletes a billing agreement.
BAUpdate Request Message
BAUpdate Request Fields
BAUpdate Response Message
BAUpdate Response Fields
Field Description
METHOD (Required) Must be BillAgreementUpdate.
REFERENCEID (Required) An ID, such as a billing agreement ID or a reference transaction ID that is
associated with a billing agreement.
BILLINGAGREEMENTSTA
TUS
(Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the
value Canceled.
NOTE:If you do not pass the value Canceled, BAUpdate returns the buyer’s latest
billing address.
L_BILLINGAGREEMENTD
ESCRIPTIONn
(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
L_BILLINGAGREEMENTC
USTOMn
(Optional) Custom annotation field for your own use.
NOTE:For recurring payments, this field is ignored.
Character length and limitations: 256 single-byte alphanumeric characters
Field Description
L_BILLINGTYPEnType of billing agreement.
L_BILLINGAGREEMENTD
ESCRIPTIONn
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
Name-Value Pair API Developer Guide August 2012 169
Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation 12
Payer Information Fields
Payer Name Fields
L_BILLINGAGREEMENTC
USTOMn
Custom annotation field for your own use.
Character length and limitations: 256 single-byte alphanumeric characters
BILLINGAGREEMENTSTA
TUS
(Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the
value Canceled.
NOTE:If you do not pass the value Canceled, BAUpdate returns the buyer’s latest
billing address.
L_BILLINGAGREEMENTM
AXn
Maximum amount for this billing agreement.
NOTE:This field only has a value if the buyer signed up for PayPal using
Preapproved Payments; it is included for backwards compatibility with
legacy systems.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
EMAIL Email address of buyer.
Character length and limitations: 127 single-byte characters
PAYERID Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters
PAYERSTATUS Status of buyer. It is one of the following values:
-verified
-unverified
Character length and limitations: 10 single-byte alphabetic characters
COUNTRYCODE 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 Buyer’s business name.
Character length and limitations: 127 single-byte characters
Field Description
SALUTATION Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FIRSTNAME Buyer’s first name.
Character length and limitations: 25 single-byte characters
Field Description
Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation
12
170 August 2012 Name-Value Pair API Developer Guide
Bill To Address Fields
MIDDLENAME Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LASTNAME Buyer’s last name.
Character length and limitations: 25 single-byte characters
SUFFIX Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
BILLINGNAME Billing name associated with this billing address.
Character length and limitations: 32 single-byte characters
STREET First billing street address.
Character length and limitations: 100 single-byte characters
STREET2 Second billing street address.
Character length and limitations: 100 single-byte characters
CITY Name of billing city.
Character length and limitations: 40 single-byte characters
STATE Billing state or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters
ZIP U.S. billing ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
COUNTRYCODE Billing country code.
Character length and limitations: 2 single-byte characters
Field Description
Name-Value Pair API Developer Guide August 2012 171
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
DoReferenceTransaction API Operation
The DoReferenceTransaction API operation processes a payment from a buyer’s account,
which is identified by a previous transaction.
DoReferenceTransaction Request Message
DoReferenceTransaction Request Fields
Field Description
METHOD (Required) Must be DoReferenceTransaction.
REFERENCEID (Required) A transaction ID from a previous purchase, such as a credit card charge
using the DoDirectPayment API, or a billing agreement ID.
PAYMENTACTION (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.
IPADDRESS (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
RETURNFMFDETAILS (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
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
172 August 2012 Name-Value Pair API Developer Guide
Ship To Address Fields
SOFTDESCRIPTOR (Optional) Per transaction description of the payment that is passed to the consumer’s
credit card statement.
If the API request provides a value for the soft descriptor field, the full descriptor
displayed on the buyer’s statement has the following format:
<PP * | PAYPAL *><Merchant descriptor as set in the Payment
Receiving Preferences><1 space><soft descriptor>
The soft descriptor can contain only the following characters:
-Alphanumeric characters
-- (dash)
-* (asterisk)
-. (period)
- {space}
If you use any other characters (such as “,”), PayPal returns an error code. The soft
descriptor does not include the phone number, which can be toggled between the
merchant’s customer service number and PayPal’s customer service number. The
maximum length of the total soft descriptor is 22 characters. Of this, the PayPal prefix
uses either 4 or 8 characters shown in the data format. Thus, the maximum length of
the soft descriptor passed in the API request is:
22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment
Receiving Preferences> + 1)
For example, assume the following conditions:
-The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.
-The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
-The soft descriptor is passed in as JanesFlowerGifts LLC
The resulting descriptor string on the credit card would be:
PAYPAL *EBAY JanesFlow
PAYMENTREQUEST_n_PA
YMENTREASON
Indicates the type of transaction. It is one of the following values:
-None – Transaction is not identified as a particular type.
-Refund – Identifies the transaction as a refund.
MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
SHIPTONAME Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
Field Description
Name-Value Pair API Developer Guide August 2012 173
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
Payment Details Fields
SHIPTOSTREET First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 (Optional) Second street address.
Character length and limitations: 100 single-byte characters
SHIPTOCITY Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOZIP 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
SHIPTOCOUNTRY Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
SHIPTOPHONENUM (Optional) Phone number.
Character length and limitations: 20 single-byte characters
Field Description
AMT (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.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
CURRENCYCODE (Optional) A 3-character currency code (default is USD).
ITEMAMT (Optional) Sum of cost of all items in this order.
NOTE:ITEMAMT is required if you specify L_AMTn.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
174 August 2012 Name-Value Pair API Developer Guide
SHIPPINGAMT (Optional) Total shipping costs for this order.
NOTE:If you specify a value for SHIPPINGAMT, you must also specify a value for
ITEMAMT.
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 (,).
HANDLINGAMT (Optional) Total handling costs for this order.
NOTE:If you specify a value for HANDLINGAMT, you must also specify a value for
ITEMAMT.
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 (,).
TAXAMT (Optional) Sum of tax for all items in this order.
NOTE:TAXAMT is required if you specify L_TAXAMTn
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 (,).
DESC (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 (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
INVNUM (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 (Optional) An identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
Field Description
Name-Value Pair API Developer Guide August 2012 175
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
Payment Details Item Fields
NOTIFYURL (Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL from
your Merchant Profile is used, if one exists.
IMPORTANT:The notify URL applies only to DoExpressCheckoutPayment.
This value is ignored when set in SetExpressCheckout or
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
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.
Field Description
L_ITEMCATEGORYnIndicates whether the item is digital or physical. For digital goods, this field is
required and you must set it to Digital to get the best rates. These parameters must
be ordered sequentially beginning with 0 (for example L_ITEMCATEGORY0,
L_ITEMCATEGORY1). It is one of the following values:
-Digital
-Physical
This field is introduced in version 69.0.
L_NAMEnItem name. This field is required when you pass a value for
L_PAYMENTREQUEST_n_ITEMCATEGORYm. These parameters must be ordered
sequentially beginning with 0 (for example L_NAME0, L_NAME1).
Character length and limitations: 127 single-byte characters
L_DESCn(Optional) Item description.
This field is available since version 53.0.
Character length and limitations: 127 single-byte characters
L_AMTnCost of item. This field is required when you pass a value for
L_PAYMENTREQUEST_n_ITEMCATEGORYm. These parameters must be ordered
sequentially beginning with 0 (for example L_AMT0, L_AMT1).
NOTE:If you specify a value for L_AMTn, you must specify a value for ITEMAMT.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
176 August 2012 Name-Value Pair API Developer Guide
Ebay Item Payment Details Item Fields
L_NUMBERn(Optional) Item number. These parameters must be ordered sequentially beginning
with 0 (for example L_NUMBER0, L_NUMBER1).
Character length and limitations: 127 single-byte characters
L_QTYnItem quantity. This field is required when you pass a value for
L_PAYMENTREQUEST_n_ITEMCATEGORYm. These parameters must be ordered
sequentially beginning with 0 (for example L_QTY0, L_QTY1).
Character length and limitations: Any positive integer
L_TAXAMTn(Optional) Item sales tax. These parameters must be ordered sequentially beginning
with 0 (for example L_TAXAMT0, L_TAXAMT1).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Field Description
L_EBAYITEMNUMBERn(Optional) Auction item number. These parameters must be ordered sequentially
beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1).
Character length: 765 single-byte characters
L_EBAYITEMAUCTIONTX
NIDn
(Optional) Auction transaction identification number. These parameters must be
ordered sequentially beginning with 0 (for example L_EBAYITEMAUCTIONTXNID0,
L_EBAYITEMAUCTIONTXNID1).
Character length: 255 single-byte characters
L_EBAYITEMORDERIDn(Optional) Auction order identification number. These parameters must be ordered
sequentially beginning with 0 (for example L_EBAYITEMORDERID0,
L_EBAYITEMORDERID1).
Character length: 64 single-byte characters
Field Description
Name-Value Pair API Developer Guide August 2012 177
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
Reference Credit Card Details Fields
Payer Information Fields
Field Description
CREDITCARDTYPE (Optional) Type of credit card. Is one of the following values:
-Visa
-MasterCard
-Discover
-Amex
-Maestro: See note.
For UK, only Maestro, MasterCard, Discover, and Visa are allowable. For
Canada, only MasterCard and Visa are allowable. Interac debit cards are not
supported.
NOTE:If the credit card type is Maestro, you must set CURRENCYCODE to GBP. In
addition, you must specify either STARTDATE or ISSUENUMBER.
Character length and limitations: Up to 10 single-byte alphabetic characters
ACCT (Optional) Credit card number.
Character length and limitations: Numeric characters only with no spaces or
punctutation. The string must conform with modulo and length required by each
credit card type.
EXPDATE Credit card expiration date. This field is required if you are using recurring payments
with direct payments.
Character length and limitations: 6 single-byte alphanumeric characters, including
leading zero, in the format MMYYYY
CVV2 (Optional) Card Verification Value, version 2. To comply with credit card processing
regulations, you must not store this value after a transaction has been completed.
Character length and limitations: For Visa, MasterCard, and Discover, the value is
exactly 3 digits. For American Express, the value is exactly 4 digits.
STARTDATE (Optional) Month and year that Maestro card was issued.
Character length and limitations: Must be 6 digits, including leading zero, in the
format MMYYYY
ISSUENUMBER (Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum.
Field Description
EMAIL (Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters
FIRSTNAME (Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
178 August 2012 Name-Value Pair API Developer Guide
Address Fields
DoReferenceTransaction Response Message
DoReferenceTransaction Response Fields for Express Checkout
LASTNAME (Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Field Description
STREET (Optional) First street address.
Character length and limitations: 100 single-byte characters
STREET2 (Optional) Second street address.
Character length and limitations: 100 single-byte characters
CITY (Optional) Name of city.
Character length and limitations: 40 single-byte characters
STATE (Optional) State or province.
Character length and limitations: 40 single-byte characters
COUNTRYCODE (Optional) Country code.
Character limit: 2 single-byte characters
ZIP (Optional) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM (Optional) Phone number.
Character length and limit: 20 single-byte characters
Field Description
AVSCODE Address Verification System response code.
Character limit: 1 single-byte alphanumeric character
CVV2MATCH Result of the CVV2 check by PayPal.
BILLINGAGREEMENTID Billing agreement identifier returned if the value of ReferenceID in the request is a
billing agreement identification number.
Field Description
Name-Value Pair API Developer Guide August 2012 179
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
Payment Information Fields
L_FMFfilterIDn Filter ID, including the filter type (PENDING, REPORT, or DENY), the filter ID, and
the entry number, n, starting from 0. Filter ID 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
L_FMFfilterNAMEnFilter name, including the filter type (PENDING, REPORT, or DENY), the filter NAME,
and the entry number, n, starting from 0.
PAYMENTADVICECODE Response code from the processor when a recurring transaction is declined. For
details on the meanings of the codes, see https://merchant.paypal.com/us/cgi-
bin/?&cmd=_render-content&content_ID=merchant/cc_compliance_error_codes
This field is available since version 84.0.
MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
TRANSACTIONID Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters
Field Description
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
180 August 2012 Name-Value Pair API Developer Guide
PARENTTRANSACTIONID 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 Receipt identification number
Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format
TRANSACTIONTYPE The type of transaction. It is one of the following values:
-cart
-express-checkout
Character length and limitations:15 single-byte characters
PAYMENTTYPE 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
ORDERTIME Time/date stamp of payment,
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z
AMT 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 (,).
CURRENCYCODE A 3-character currency code.
FEEAMT 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 (,).
Field Description
Name-Value Pair API Developer Guide August 2012 181
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
SETTLEAMT 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 (,).
TAXAMT Tax charged on the transaction.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
EXCHANGERATE Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency. If the buyer chooses to pay with a currency other than the
non-primary currency, the conversion occurs in the buyer’s account.
Character length and limitations: Decimal value that does not exceed 17 characters,
including decimal point
PAYMENTSTATUS Status of the payment. It is one of the following values:
-None – No status
-Canceled-Reversal– A reversal has been canceled, for example, when you
win a dispute and the funds for the reversal have been returned to you.
-Completed – The payment has been completed, and the funds have been added
successfully to your account balance.
-Denied – You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the
PendingReason element.
-Expired – The authorization period for this payment has been reached.
-Failed – The payment has failed. This happens only if the payment was made
from your buyer’s bank account.
-In-Progress – The transaction has not terminated, for example, an
authorization may be awaiting completion.
-Partially-Refunded – The payment has been partially refunded.
-Pending – The payment is pending. See the PendingReason field for more
information.
-Refunded – You refunded the payment.
-Reversed – A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer. The reason for the reversal is specified in the ReasonCode element.
-Processed – A payment has been accepted.
-Voided – An authorization for this transaction has been voided.
Field Description
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
182 August 2012 Name-Value Pair API Developer Guide
PENDINGREASON The reason the payment is pending. It is one of the following values:
-none – No pending reason.
-address – The payment is pending because your buyer did not include a
confirmed shipping address and your Payment Receiving Preferences is set such
that you want to manually accept or deny each of these payments. To change your
preference, go to the Preferences section of your Profile.
-authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
-echeck – The payment is pending because it was made by an eCheck that has not
yet cleared.
-intl – The payment is pending because you hold a non-U.S. account and do not
have a withdrawal mechanism. You must manually accept or deny this payment
from your Account Overview.
-multi-currency – You do not have a balance in the currency sent, and you do
not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this payment.
-order – The payment is pending because it is part of an order that has been
authorized but not settled.
-paymentreview – The payment is pending while it is being reviewed by PayPal
for risk.
-unilateral – The payment is pending because it was made to an email address
that is not yet registered or confirmed.
-verify –The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
-other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal Customer Service.
NOTE:PendingReason is returned in the response only if PaymentStatus is
Pending.
REASONCODE The reason for a reversal if the transaction type is reversal. It is one of the following
values:
-none – No reason code.
-chargeback – A reversal has occurred on this transaction due to a chargeback by
your buyer.
-guarantee – A reversal has occurred on this transaction due to your buyer
triggering a money-back guarantee.
-buyer-complaint – A reversal has occurred on this transaction due to a
complaint about the transaction from your buyer.
-refund – A reversal has occurred on this transaction because you have given the
buyer a refund.
-other – A reversal has occurred on this transaction due to a reason not listed
above.
Field Description
Name-Value Pair API Developer Guide August 2012 183
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation 12
PROTECTIONELIGIBILI
TY
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
Since version 64.4, the kind of seller protection in force for the transaction. It is one
of the following values:
-Eligible – Merchant is protected by PayPal's Seller Protection Policy for both
Unauthorized Payment and Item Not Received.
-ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received.
-UnauthorizedPaymentEligible – Merchant is protected by PayPal's Seller
Protection Policy for Unauthorized Payment.
-Ineligible – Merchant is not protected under the Seller Protection Policy.
This field is introduced in API version 64.4.
STOREID xs:string
StoreId as entered in the transaction.
TERMINALID xs:string
TerminalId as entered in the transaction.
Field Description
Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation
12
184 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 185
13 RefundTransaction API Operation
The RefundTransaction API operation issues a refund to the PayPal account holder associated
with a transaction.
RefundTransaction Request Message
RefundTransaction Request Fields
Field Description
METHOD (Required) Must be RefundTransaction.
TRANSACTIONID (Required) Unique identifier of the transaction to be refunded.
Character length and limitations: 17 single-byte alphanumeric characters
INVOICEID (Optional) Your own invoice or tracking number.
Character length and limitations: 127 single-byte alphanumeric characters
REFUNDTYPE Type of refund you are making. It is one of the following values:
-Full – Full refund (default).
-Partial – Partial refund.
-ExternalDispute – External dispute. (Value available since version 82.0)
-Other – Other type of refund. (Value available since version 82.0)
AMT (Optional) Refund amount. The amount is required if RefundType is Partial.
NOTE:If RefundType is Full, do not set the amount.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
CURRENCYCODE ISO 4217 3-letter currency code. USD for US Dollars. This field is required for
partial refunds, and is also required for refunds greater than 100%.
Character length and limitations: 3 single-byte characters
NOTE (Optional) Custom memo about the refund.
Character length and limitations: 255 single-byte alphanumeric characters
RefundTransaction API Operation
RefundTransaction Request Message
13
186 August 2012 Name-Value Pair API Developer Guide
Merchant Store Details Fields
RETRYUNTIL (Optional) Maximum time until you must retry the refund.
NOTE:This field does not apply to point-of-sale transactions.
This field is available since version 82.0.
REFUNDSOURCE (Optional)Type of PayPal funding source (balance or eCheck) that can be used for
auto refund. It is one of the following values:
-any – The merchant does not have a preference. Use any available funding
source.
-default – Use the merchant’s preferred funding source, as configured in the
merchant’s profile.
-instant – Use the merchant’s balance as the funding source.
-eCheck – The merchant prefers using the eCheck funding source. If the
merchant’s PayPal balance can cover the refund amount, use the PayPal balance.
NOTE:This field does not apply to point-of-sale transactions.
This field is available since version 82.0.
MERCHANTSTOREDETAIL
S
(Optional) Information about the merchant store.
This field is available since version 82.0.
REFUNDADVICE (Optional) Flag to indicate that the buyer was already given store credit for a given
transaction. It is one of the following values:
-true – The buyer was already given store credit for a given transaction.
-false – The buyer was not given store credit for a given transaction.
This field is available since version 85.0.
REFUNDITEMDETAILS (Optional) Details about the individual items to be returned.
MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
STOREID Identifier of the merchant store at which the refund is given. This field is
required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
Field Description
Name-Value Pair API Developer Guide August 2012 187
RefundTransaction API Operation
RefundTransaction Response Message 13
RefundTransaction Response Message
RefundTransaction Response Fields
TERMINALID (Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
Field Description
REFUNDTRANSACTIONID Unique transaction ID of the refund.
Character length and limitations:17 single-byte characters
FEEREFUNDAMT Transaction fee refunded to original recipient of payment.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
GROSSREFUNDAMT Amount refunded to the original payer. Say, for example, a buyer makes $100
purchase, the buyer was refunded $20 a week ago and is refunded $30 in this
transaction. The gross refund amount is $30 (in this transaction).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
NETREFUNDAMT Amount subtracted from PayPal balance of the original recipient of payment, to make
this refund.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TOTALREFUNDEDAMT Total amount refunded so far from the original purchase. Say, for example, a buyer
makes $100 purchase, the buyer was refunded $20 a week ago and is refunded $30 in
this transaction. The gross refund amount is $30 (in this transaction). The total
refunded amount is $50.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
This field is available since version 67.0.
Field Description
RefundTransaction API Operation
RefundTransaction Response Message
13
188 August 2012 Name-Value Pair API Developer Guide
RefundInfoType Fields
CURRENCYCODE Currency code.
Character length and limitations: 3 single-byte characters
REFUNDINFO Contains refund payment status information.
This field is available since version 84.0.
MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Field Description
REFUNDSTATUS ns:PaymentStatusCodeType
Status of the refund. It is one of the following values:
-instant
-delayed
This field is available since version 84.0.
PENDINGREASON Reason that the refund payment status is delayed. It is one of the following values:
-none – The refund status is instant.
-echeck – The refund status is delayed.
This field is available since version 84.0.
Field Description
Name-Value Pair API Developer Guide August 2012 189
14 TransactionSearch API Operation
The TransactionSearch API searches transaction history for transactions that meet the
specified criteria.
NOTE:The maximum number of transactions that can be returned from a TransactionSearch
API call is 100.
TransactionSearch Request Message
TransactionSearch Request Fields
Field Description
METHOD (Required) Must be TransactionSearch.
STARTDATE (Required) The earliest transaction date at which to start the search.
Character length and limitations: No wildcards are allowed. The value must be in
UTC/GMT.
ENDDATE (Optional) The latest transaction date to be included in the search.
Character length and limitations: No wildcards are allowed. The value must be in
UTC/GMT.
EMAIL (Optional) Search by the buyer’s email address.
Character length and limitations: 127 single-byte alphanumeric characters
RECEIVER (Optional) Search by the receiver’s email address. If the merchant account has only
one email address, this is the primary email. It can also be a non-primary email
address.
RECEIPTID (Optional) Search by the PayPal Account Optional receipt ID. This field is not
applicable to point-of-sale transactions.
TRANSACTIONID (Optional) Search by the transaction ID. The returned results are from the merchant’s
transaction records.
Character length and limitations: 19 single-byte characters maximum
INVNUM (Optional) Search by invoice identification key, as set by you for the original
transaction. This field searches the records for items the merchant sells.
Character length and limitations: 127 single-byte characters maximum with no
wildcards allowed
TransactionSearch API Operation
TransactionSearch Request Message
14
190 August 2012 Name-Value Pair API Developer Guide
ACCT (Optional) Search by credit card number, as set by you for the original transaction.
This field searches the records for items the merchant sells. The field is not applicable
to point-of-sale.
NOTE:No wildcards are allowed.
Character length and limitations: Must be at least 11 and no more than 25 single-byte
numeric characters maximum. Special punctuation, such as dashes or spaces, is
ignored.
AUCTIONITEMNUMBER (Optional) Search by auction item number of the purchased goods. This field is not
applicable to point-of-sale.
TRANSACTIONCLASS (Optional) Search by classification of transaction. Some kinds of possible classes of
transactions are not searchable with this field. You cannot search for bank transfer
withdrawals, for example. It is one of the following values:
-All – All transaction classifications
-Sent – Only payments sent
-Received – Only payments received
-MassPay – Only mass payments
-MoneyRequest – Only money requests
-FundsAdded – Only funds added to balance
-FundsWithdrawn – Only funds withdrawn from balance
-Referral – Only transactions involving referrals
-Fee – Only transactions involving fees
-Subscription – Only transactions involving subscriptions
-Dividend – Only transactions involving dividends
-Billpay – Only transactions involving BillPay Transactions
-Refund – Only transactions involving funds
-CurrencyConversions – Only transactions involving currency conversions
-BalanceTransfer – Only transactions involving balance transfers
-Reversal – Only transactions involving BillPay reversals
-Shipping – Only transactions involving UPS shipping fees
-BalanceAffecting – Only transactions that affect the account balance
-ECheck – Only transactions involving eCheck
AMT (Optional) Search by transaction amount.
NOTE:You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
CURRENCYCODE (Optional) Search by 3-character, ISO 4217 currency code.
Field Description
Name-Value Pair API Developer Guide August 2012 191
TransactionSearch API Operation
TransactionSearch Request Message 14
Payer Name Fields
STATUS (Optional) Search by transaction status. It is one of the following values:
-Pending – The payment is pending. The specific reason the payment is pending
is returned by the GetTransactionDetails API PendingReason field.
-Processing – The payment is being processed.
-Success – The payment has been completed and the funds have been added
successfully to your account balance.
-Denied – You denied the payment. This happens only if the payment was
previously pending.
-Reversed – A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer.
PROFILEID (Optional) An alphanumeric string (generated by PayPal) that uniquely identifies a
recurring profile. You can specify the Profile ID in the TransactionSearch API
operation to obtain all payments associated with the identified profile.
Field Description
SALUTATION (Optional) Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FIRSTNAME (Optional) Buyer’s first name.
Character length and limitations: 25 single-byte characters
MIDDLENAME (Optional) Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LASTNAME (Optional) Buyer’s last name.
Character length and limitations: 25 single-byte characters
SUFFIX (Optional) Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Field Description
TransactionSearch API Operation
TransactionSearch Response Message
14
192 August 2012 Name-Value Pair API Developer Guide
TransactionSearch Response Message
TransactionSearch Response Fields
Field Description
L_TIMESTAMPn Date and time in UTC/GMT that the transaction occurred.
L_TIMEZONEn Time zone of the transaction. The value is always GMT.
L_TYPEn Type of the transaction. It is one of the following values:
-Currency Conversion (credit)
-Currency Conversion (debit)
-Payment
-Recurring Payment
-Temporary Hold
-Transfer
-Donation
L_EMAILn Email address of either the buyer or the payment recipient (the “payee”). If the
payment amount is positive, this field is the recipient of the funds. If the payment is
negative, this field is the paying buyer.
L_NAMEn Display name of the buyer.
L_TRANSACTIONIDn Merchant’s transaction ID.
L_STATUSn The status of the transaction.
L_AMTn The total gross amount charged, including any profile shipping cost and taxes.
L_CURRENCYCODEn3-character, ISO 4217 currency code.
L_FEEAMTn The fee that PayPal charged for the transaction.
L_NETAMTn The net amount of the transaction.
Name-Value Pair API Developer Guide August 2012 193
AAPI Error Codes
The PayPal API can return multiple errors for any operation.
General API Errors
General API Errors
Error
Code Short Message Long Message Correcting This Error
10002 Authentication/Authoriza
tion Failed
Username/Password is incorrect This error can be caused by an incorrect
API username, an incorrect API
password, or an invalid API signature.
Make sure that all three of these values
are correct. For your security, PayPal
does not report exactly which of these
three values might be in error.
10002 Authentication/Authoriza
tion Failed
You do not have permission to
make this API call
10002 Authentication/Authoriza
tion Failed
Account is locked or inactive
10002 Internal Error Internal Error
10002 Authentication/Authoriza
tion Failed
Internal Error
10002 Authentication/Authoriza
tion Failed
Account is not verified
10002 Authentication/Authoriza
tion Failed
This call is not defined in the
database!
10002 Authentication/Authoriza
tion Failed
Token is not valid
10002 Restricted account Account is restricted Your PayPal merchant account has been
restricted. Contact your PayPal account
manager for resolution.
10002 Authentication/Authoriza
tion Failed
API access is disabled for this
account
API Error Codes
Validation Errors
A
194 August 2012 Name-Value Pair API Developer Guide
Validation Errors
Validation Errors
10002 Authentication/Authoriza
tion Failed
Client certificate is disabled
10006 Version error Version is not supported
10008 Security error Security header is not valid
10101 This API Temporarily
Unavailable
This API is temporarily
unavailable. Please try later.
Error Code Short Message Long Message
81000 Missing Parameter Required Parameter Missing : Unable to identify
parameter
81001 Invalid Parameter A Parameter is Invalid : Unable to identify parameter
81002 Unspecified Method Method Specified is not Supported
81003 Unspecified Method No Method Specified
81004 Unspecified Method No Request Received
81100 Missing Parameter OrderTotal (Amt) : Required parameter missing
81101 Missing Parameter MaxAmt : Required parameter missing
81102 Missing Parameter ReturnURL: Required parameter missing
81103 Missing Parameter NotifyURL : Required parameter missing
81104 Missing Parameter CancelURL : Required parameter missing
81105 Missing Parameter ShipToStreet : Required parameter missing
81106 Missing Parameter ShipToStreet2 : Required parameter missing
81107 Missing Parameter ShipToCity : Required parameter missing
81108 Missing Parameter ShipToState : Required parameter missing
81109 Missing Parameter ShipToZip : Required parameter missing
81110 Missing Parameter Country : Required parameter missing
81111 Missing Parameter ReqConfirmShipping : Required parameter missing
81112 Missing Parameter NoShipping : Required parameter missing
81113 Missing Parameter AddrOverride : Required parameter missing
Error
Code Short Message Long Message Correcting This Error
Name-Value Pair API Developer Guide August 2012 195
API Error Codes
Validation Errors A
81114 Missing Parameter LocaleCode : Required parameter missing
81115 Missing Parameter PaymentAction : Required parameter missing
81116 Missing Parameter Email : Required parameter missing
81117 Missing Parameter Token : Required parameter missing
81118 Missing Parameter PayerID : Required parameter missing
81119 Missing Parameter ItemAmt : Required parameter missing
81120 Missing Parameter ShippingAmt : Required parameter missing
81121 Missing Parameter HandlingAmt : Required parameter missing
81122 Missing Parameter TaxAmt : Required parameter missing
81123 Missing Parameter IPAddress : Required parameter missing
81124 Missing Parameter ShipToName : Required parameter missing
81125 Missing Parameter L_Amt : Required parameter missing
81126 Missing Parameter Amt : Required parameter missing
81127 Missing Parameter L_TaxAmt : Required parameter missing
81128 Missing Parameter AuthorizationID : Required parameter missing
81129 Missing Parameter CompleteType : Required parameter missing
81130 Missing Parameter CurrencyCode : Required parameter missing
81131 Missing Parameter TransactionID : Required parameter missing
81132 Missing Parameter TransactionEntity : Required parameter missing
81133 Missing Parameter Acct : Required parameter missing
81134 Missing Parameter ExpDate : Required parameter missing
81135 Missing Parameter FirstName : Required parameter missing
81136 Missing Parameter LastName : Required parameter missing
81137 Missing Parameter Street : Required parameter missing
81138 Missing Parameter Street2 : Required parameter missing
81139 Missing Parameter City : Required parameter missing
81140 Missing Parameter State : Required parameter missing
81141 Missing Parameter Zip : Required parameter missing
81142 Missing Parameter CountryCode : Required parameter missing
81143 Missing Parameter RefundType : Required parameter missing
81144 Missing Parameter StartDate : Required parameter missing
Error Code Short Message Long Message
API Error Codes
Validation Errors
A
196 August 2012 Name-Value Pair API Developer Guide
81145 Missing Parameter EndDate : Required parameter missing
81146 Missing Parameter MPID : Required parameter missing
81147 Missing Parameter CreditCardType : Required parameter missing
81148 Missing Parameter User : Required parameter missing
81149 Missing Parameter Pwd : Required parameter missing
81150 Missing Parameter Version : Required parameter missing
81200 Missing Parameter Amt : Invalid parameter
81201 Invalid Parameter MaxAmt : Invalid parameter
81203 Invalid Parameter NotifyURL : Invalid parameter
81205 Invalid Parameter ShipToStreet : Invalid parameter
81206 Invalid Parameter ShipToStreet2 : Invalid parameter
81207 Invalid Parameter ShipToCity : Invalid parameter
81208 Invalid Parameter ShipToState : Invalid parameter
81209 Invalid Parameter ShipToZip : Invalid parameter
81210 Invalid Parameter Country : Invalid parameter
81211 Invalid Parameter ReqConfirmShipping : Invalid parameter
81212 Invalid Parameter Noshipping : Invalid parameter
81213 Invalid Parameter AddrOverride : Invalid parameter
81214 Invalid Parameter LocaleCode : Invalid parameter
81215 Invalid Parameter PaymentAction : Invalid parameter
81219 Invalid Parameter ItemAmt : Invalid parameter
81220 Invalid Parameter ShippingAmt : Invalid parameter
81221 Invalid Parameter HandlingTotal Amt : Invalid parameter
81222 Invalid Parameter TaxAmt : Invalid parameter
81223 Invalid Parameter IPAddress : Invalid parameter
81224 Invalid Parameter ShipToName : Invalid parameter
81225 Invalid Parameter L_Amt : Invalid parameter
81226 Invalid Parameter Amt : Invalid parameter
81227 Invalid Parameter L_TaxAmt : Invalid parameter
81229 Invalid Parameter CompleteType : Invalid parameter
81230 Invalid Parameter CurrencyCode : Invalid parameter
Error Code Short Message Long Message
Name-Value Pair API Developer Guide August 2012 197
API Error Codes
DirectPayment API Errors A
DirectPayment API Errors
DirectPayment API Errors
81232 Invalid Parameter TransactionEntity : Invalid parameter
81234 Invalid Parameter ExpDate : Invalid parameter
81235 Invalid Parameter FirstName : Invalid parameter
81236 Invalid Parameter LastName : Invalid parameter
81237 Invalid Parameter Street : Invalid parameter
81238 Invalid Parameter Street2 : Invalid parameter
81239 Invalid Parameter City : Invalid parameter
81243 Invalid Parameter RefundType : Invalid parameter
81244 Invalid Parameter StartDate : Invalid parameter
81245 Invalid Parameter EndDate : Invalid parameter
81247 Invalid Parameter CreditCardType : Invalid parameter
81248 Invalid Parameter Username : Invalid parameter
81249 Invalid Parameter Password : Invalid parameter
81250 Invalid Parameter Version : Invalid parameter
81251 Internal Error Internal Service Error
99998 Transaction refused because of an
invalid argument. See additional
error messages for details.
Currency is not supported
Error
Code Short Message Long Message Corrective Action
10102 PaymentAction of Order
Temporarily Unavailable
PaymentAction of Order is
temporarily unavailable. Please
try later or use other
PaymentAction.
10401 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Order total is missing.
Error Code Short Message Long Message
API Error Codes
DirectPayment API Errors
A
198 August 2012 Name-Value Pair API Developer Guide
10418 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The currencies of the shopping
cart amounts must be the same.
10426 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item total is invalid.
10427 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Shipping total is invalid.
10428 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Handling total is invalid.
10429 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Tax total is invalid.
10432 Invalid argument Invoice ID value exceeds
maximum allowable length.
10485 Payment not authorized Payment has not been authorized
by the user.
10500 Invalid Configuration This transaction cannot be
processed due to an invalid
merchant configuration.
Occurs when you have not agreed to the
billing agreement.
10501 Invalid Configuration This transaction cannot be
processed due to an invalid
merchant configuration.
Occurs when the billing agreement is
disabled or inactive.
10502 Invalid Data This transaction cannot be
processed. Please use a valid
credit card.
The credit card used is expired.
10504 Invalid Data This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
The CVV provided is invalid. The CVV
is between 3-4 digits long.
10505 Gateway Decline This transaction cannot be
processed.
The transaction was refused because the
AVS response returned the value of N,
and the merchant account is not able to
accept such transactions.
Error
Code Short Message Long Message Corrective Action
Name-Value Pair API Developer Guide August 2012 199
API Error Codes
DirectPayment API Errors A
10507 Invalid Configuration This transaction cannot be
processed. Please contact PayPal
Customer Service.
Your PayPal account is restricted.
Contact PayPal for more information.
10508 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card expiration date.
The expiration date must be a two-digit
month and four-digit year.
10509 Invalid Data This transaction cannot be
processed.
You must submit an IP address of the
buyer with each API call.
10510 Invalid Data The credit card type is not
supported. Try another card type.
The credit card type entered is not
currently supported by PayPal.
10511 Invalid Data This transaction cannot be
processed.
The merchant selected a value for the
PaymentAction field that is not
supported.
10512 Invalid Data This transaction cannot be
processed. Please enter a first
name.
The first name of the buyer is required
for this merchant.
10513 Invalid Data This transaction cannot be
processed. Please enter a last
name.
The last name of the buyer is required
for this merchant.
10519 Invalid Data Please enter a credit card. The credit card field was blank.
10520 Invalid Data This transaction cannot be
processed.
The total amount and item amounts do
not match.
10521 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card.
The credit card entered is invalid.
10523 Internal Error This transaction cannot be
processed.
None. This is a PayPal internal error.
10525 Invalid Data This transaction cannot be
processed. The amount to be
charged is zero.
The merchant entered an amount of zero.
10526 Invalid Data This transaction cannot be
processed. The currency is not
supported at this time.
The currency code entered is not
supported.
10527 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is invalid.
10534 Gateway Decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is currently
restricted by PayPal. Contact PayPal for
more information.
Error
Code Short Message Long Message Corrective Action
API Error Codes
DirectPayment API Errors
A
200 August 2012 Name-Value Pair API Developer Guide
10535 Gateway Decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is invalid.
10536 Invalid Data This transaction cannot be
processed.
The merchant entered an invoice ID that
is already associated with a transaction
by the same merchant. By default, the
invoice ID must be unique for all
transactions. To change this setting, log
into PayPal or contact customer service.
10537 Filter Decline This transaction cannot be
processed.
The transaction was declined by the
country filter managed by the merchant.
To accept this transaction, change your
risk settings on PayPal.
10538 Filter Decline This transaction cannot be
processed.
The transaction was declined by the
maximum amount filter managed by the
merchant. To accept this transaction,
change your risk settings on PayPal.
10539 Filter Decline This transaction cannot be
processed.
The transaction was declined by PayPal.
Contact PayPal for more information.
10540 Invalid Data The transaction cannot be
processed due to an invalid
address.
The transaction was declined by PayPal
because of an invalid address.
10541 Gateway Decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is currently
restricted by PayPal. Contact PayPal for
more information.
10542 Invalid Data This transaction cannot be
processed. Please enter a valid
email address.
The email address provided by the buyer
is in an invalid format.
10544 Gateway Decline This transaction cannot be
processed.
The transaction was declined by PayPal.
Contact PayPal for more information.
10545 Gateway Decline This transaction cannot be
processed.
The transaction was declined by PayPal
because of possible fraudulent activity.
Contact PayPal for more information.
10546 Gateway Decline This transaction cannot be
processed.
The transaction was declined by PayPal
because of possible fraudulent activity
on the IP address. Contact PayPal for
more information.
10547 Internal Error This transaction cannot be
processed.
None. This is a PayPal internal error.
Error
Code Short Message Long Message Corrective Action
Name-Value Pair API Developer Guide August 2012 201
API Error Codes
DirectPayment API Errors A
10548 Invalid Configuration This transaction cannot be
processed. The merchant’s
account is not able to process
transactions.
The merchant account attempting the
transaction is not a business account at
PayPal. Check your account settings.
10549 Invalid Configuration This transaction cannot be
processed. The merchan’s
account is not able to process
transactions.
The merchant account attempting the
transaction is not able to process Direct
Payment transactions. Contact PayPal
for more information.
10550 Invalid Configuration This transaction cannot be
processed.
Access to Direct Payment was disabled
for your account. Contact PayPal for
more information.
10552 Invalid Configuration This transaction cannot be
processed.
The merchant account attempting the
transaction does not have a confirmed
email address with PayPal. Check your
account settings.
10553 Gateway Decline This transaction cannot be
processed.
The merchant attempted a transaction
where the amount exceeded the upper
limit for that merchant.
10554 Filter Decline This transaction cannot be
processed.
The transaction was declined because of
a merchant risk filter for AVS.
Specifically, the merchant has set to
decline transaction when the AVS
returned a no match (AVS = N).
10555 Filter Decline This transaction cannot be
processed.
The transaction was declined because of
a merchant risk filter for AVS.
Specifically, the merchant has set the
filter to decline transactions when the
AVS returns a partial match.
10556 Filter Decline This transaction cannot be
processed.
The transaction was declined because of
a merchant risk filter for AVS.
Specifically, the merchant has set the
filter to decline transactions when the
AVS is unsupported.
10561 Invalid Data There’s an error with this
transaction. Please enter
complete billing address.
10562 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card expiration year.
10563 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card expiration month.
Error
Code Short Message Long Message Corrective Action
API Error Codes
DirectPayment API Errors
A
202 August 2012 Name-Value Pair API Developer Guide
10564 Gateway Decline This transaction cannot be
processed.
There was a problem processing this
transaction.
10565 Merchant country
unsupported
The merchant country is not
supported.
10566 Credit card type
unsupported
The credit card type is not
supported.
10567 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card number and type.
10571 Transaction approved, but
with invalid Card
Security Code (CSC)
format.
This transaction was approved,
although the Card Security Code
(CSC) had too few, too many, or
invalid characters. Based on your
account profile settings, the
invalid CSC was not given to the
card issuer for its approval
process.
If you want to require valid CVV values,
change the risk control settings in your
account profile.
10701 Invalid Data There’s an error with this
transaction. Please enter a valid
billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10702 Invalid Data There’s an error with this
transaction. Please enter a valid
address1 in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10703 Invalid Data There’s an error with this
transaction. Please enter a valid
address2 in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10704 Invalid Data There’s an error with this
transaction. Please enter a valid
city in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10705 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10706 Invalid Data There’s an error with this
transaction. Please enter a valid
postal code in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10707 Invalid Data There’s an error with this
transaction. Please enter a valid
country in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
Error
Code Short Message Long Message Corrective Action
Name-Value Pair API Developer Guide August 2012 203
API Error Codes
DirectPayment API Errors A
10708 Invalid Data There’s an error with this
transaction. Please enter a
complete billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10709 Invalid Data There’s an error with this
transaction. Please enter an
address1 in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10709 Invalid Data There’s an error with this
transaction. Please enter an
address1 in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10710 Invalid Data There’s an error with this
transaction. Please enter a city in
the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10710 Invalid Data There’s an error with this
transaction. Please enter a city in
the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10711 Invalid Data There’s an error with this
transaction. Please enter your
state in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10712 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10713 Invalid Data There’s an error with this
transaction. Please enter a
country in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10713 Invalid Data There’s an error with this
transaction. Please enter a
country in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10714 Invalid Data There’s an error with this
transaction. Please enter a valid
billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10715 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10716 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
Error
Code Short Message Long Message Corrective Action
API Error Codes
DirectPayment API Errors
A
204 August 2012 Name-Value Pair API Developer Guide
10717 Invalid Data There’s an error with this
transaction. Please enter a valid
postal code in the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10718 Invalid Data There’s an error with this
transaction. Please enter a valid
city and state in the billing
address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10719 Invalid Data There’s an error with this
transaction. Please enter a valid
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10720 Invalid Data There’s an error with this
transaction. Please enter a valid
address1 in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10721 Invalid Data There’s an error with this
transaction. Please enter a valid
address2 in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10722 Invalid Data There’s an error with this
transaction. Please enter a valid
city in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10723 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10724 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10725 Invalid Data There’s an error with this
transaction. Please enter a valid
country in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10726 Invalid Data There’s an error with this
transaction. Please enter a
complete shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10726 Invalid Data There’s an error with this
transaction. Please enter a
complete shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10727 Invalid Data There’s an error with this
transaction. Please enter an
address1 in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
Error
Code Short Message Long Message Corrective Action
Name-Value Pair API Developer Guide August 2012 205
API Error Codes
DirectPayment API Errors A
10727 Invalid Data There’s an error with this
transaction. Please enter an
address1 in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10728 Invalid Data There’s an error with this
transaction. Please enter a city in
the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10728 Invalid Data There’s an error with this
transaction. Please enter a city in
the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10729 Invalid Data There’s an error with this
transaction. Please enter your
state in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10730 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10731 Invalid Data There’s an error with this
transaction. Please enter a
country in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10731 Invalid Data There’s an error with this
transaction. Please enter a
country in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10732 Invalid Data There’s an error with this
transaction. Please enter a valid
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10733 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10734 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10735 Invalid Data There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10736 Invalid Data There’s an error with this
transaction. Please enter a valid
city and state in the shipping
address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
Error
Code Short Message Long Message Corrective Action
API Error Codes
DirectPayment API Errors
A
206 August 2012 Name-Value Pair API Developer Guide
10744 Invalid Data This transaction cannot be
processed. Please enter a valid
country code in the billing
address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10745 Invalid Data This transaction cannot be
processed. Please enter a valid
country code in the shipping
address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10746 Invalid Data This transaction cannot be
processed. Please use a valid
country on the billing address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10747 Invalid Data This transaction cannot be
processed.
The merchant entered an IP address that
was in an invalid format. The IP address
must be in a format such as
123.456.123.456.
10748 Invalid Data This transaction cannot be
processed without a Credit Card
Verification Number.
The merchant’s configuration requires a
CVV to be entered, but no CVV was
provided with this transaction. Contact
PayPal if you wish to change this setting.
10750 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the shipping address.
There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.
10751 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the billing address.
The merchant provided an address either
in the United States or Canada, but the
state provided is not a valid state in
either country.
10752 Gateway Decline This transaction cannot be
processed.
The transaction was declined by the
issuing bank, not PayPal. The merchant
should attempt another card.
10754 Gateway Decline This transaction cannot be
processed.
The transaction was declined by PayPal.
Contact PayPal for more information.
10755 Invalid Data This transaction cannot be
processed due to an unsupported
currency.
The currency code entered by the
merchant is not supported.
10756 Gateway Decline The transaction cannot be
processed. The country and
billing address associated with
this credit card do not match.
None. This is a PayPal internal error.
10758 Invalid Configuration There’s been an error due to
invalid API username and/or
password.
The API username or password is
incorrect for this merchant.
Error
Code Short Message Long Message Corrective Action
Name-Value Pair API Developer Guide August 2012 207
API Error Codes
DirectPayment API Errors A
10759 Gateway Decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
The transaction was declined by PayPal.
Contact PayPal for more information.
10760 Invalid Configuration This transaction cannot be
processed. The country listed for
your business address is not
currently supported.
The merchant’s country of residence
listed in their PayPal account is not
currently supported to allow Direct
Payment transactions.
10761 Gateway Decline This transaction cannot be
processed. Please check the
status of your first transaction
before placing another order.
The transaction was declined because
PayPal is currently processing a
transaction by the same buyer for the
same amount. Can occur when a buyer
submits multiple, identical transactions
in quick succession.
10762 Gateway Decline This transaction cannot be
processed.
The CVV provide is invalid. The CVV is
between 3-4 digits long.
10763 Invalid Data This transaction cannot be
processed.
None - this is a PayPal internal error.
10764 This transaction cannot be
processed at this time.
Please try again later.
This transaction cannot be
processed at this time. Please try
again later.
The transaction was declined by PayPal.
Please try again later. If the problem
persists, please contact PayPal.
11068 Seller restriction. All sellers restricted.
11610 Payment Pending your
review in Fraud
Management Filters
Payment Pending your review in
Fraud Management Filters
11611 Transaction blocked by
your settings in FMF
Transaction blocked by your
settings in FMF
11612 Could not process your
request to accept/deny the
transaction
Could not process your request to
accept/deny the transaction
11821 This transaction cannot be
processed
This transaction cannot be
processed because it has already
been denied by a Fraud
Management Filter
You cannot capture a payment after it
has been denied by a Fraud Management
Filter. You can control whether a Fraud
Management Filter denies a transaction
by changing the filter's settings in the
profile.
12000 Transaction is not
compliant due to missing
or invalid 3-D Secure
authentication values.
Transaction is not compliant due
to missing or invalid 3-D Secure
authentication values.
Check ECI, ECI3DS, CAVV, XID fields.
Error
Code Short Message Long Message Corrective Action
API Error Codes
DirectPayment API Errors
A
208 August 2012 Name-Value Pair API Developer Guide
12001 Transaction is not
compliant due to missing
or invalid 3-D Secure
authentication values.
Transaction is not compliant due
to missing or invalid 3-D Secure
authentication values.
Check ECI, ECI3DS, CAVV, XID fields.
15001 Gateway Decline This transaction cannot be
processed.
The transaction was rejected by PayPal
because of excessive failures over a
short period of time for this credit card.
Contact PayPal for more information.
15002 Gateway Decline This transaction cannot be
processed.
The transaction was declined by PayPal.
Contact PayPal for more information.
15003 Invalid Configuration This transaction cannot be
processed.
The transaction was declined because
the merchant does not have a valid
commercial entity agreement on file
with PayPal. Contact PayPal for more
information.
15004 Gateway Decline This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
The transaction was declined because
the CVV entered does not match the
credit card.
15005 Processor Decline This transaction cannot be
processed.
The transaction was declined by the
issuing bank, not PayPal. The merchant
should attempt another card.
15006 Processor Decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
The transaction was declined by the
issuing bank, not PayPal. The merchant
should attempt another card.
15007 Processor Decline This transaction cannot be
processed. Please use a valid
credit card.
The transaction was declined by the
issuing bank because of an expired
credit card. The merchant should attempt
another card.
15008 Invalid Data This transaction has been
completed, but the total of items
in the cart did not match the total
of all items.
15011 Gateway Decline This credit card was issued from
an unsupported country.
Error
Code Short Message Long Message Corrective Action
Name-Value Pair API Developer Guide August 2012 209
API Error Codes
SetExpressCheckout API Errors A
SetExpressCheckout API Errors
SetExpressCheckout API Errors
Error
Code Short Message Long Message Correcting This Error...
10001 ButtonSource value
truncated.
The transaction could not be loaded
10001 Internal Error Internal Error
10003 Missing argument. OtherPaymentMethodID is missing.
10003 Missing argument. OtherPaymentMethodLabel is
missing.
10003 Missing argument. OtherPaymentMethodType is
missing.
10003 Missing argument. One or more of these giropay URLs
is missing: giropaySuccessURL,
giropayCancelURL,
BanktxnPendingURL.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Transaction refused because of an
invalid argument. See additional
error messages for details.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction id is not valid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid value for request billing
address parameter.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid item URL.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
OtherPaymentMethodType is
invalid.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
RegistrationDate of buyer is invalid.
API Error Codes
SetExpressCheckout API Errors
A
210 August 2012 Name-Value Pair API Developer Guide
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback overall
positive count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback overall
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback total
positive count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback total
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback recent
positive count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay buyer feedback recent
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
SellerRegistrationDate is invalid.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback overall
positive count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback overall
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback total
positive count.
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 211
API Error Codes
SetExpressCheckout API Errors A
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback total
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback recent
positive count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay seller feedback recent
negative count.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay item transaction date.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay item buyer protection
type.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid eBay item payment hold risk.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Multiple eBay order IDs not allowed.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
AllowPushFunding value specified is
invalid. It must be 0 or 1 or an empty
string.
10005 Option not supported. Merchant not enabled to use
enhanced checkout data.
10005 Option not supported. Merchant not enabled to use
OtherPaymentMethodDetails.
10005 Option not supported. Transaction ID is not supported.
10007 Permission denied You do not have permission to make
this API call
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
212 August 2012 Name-Value Pair API Developer Guide
10010 Invalid Invoice Non-ASCII invoice id is not
supported.
10101 Option not supported. Express Checkout temporarily
unavailable. Please try later.
10102 PaymentAction of Order
Temporarily Unavailable
PaymentAction of Order is
temporarily unavailable. Please try
later or use other PaymentAction.
10103 Please use another Solution
Type.
Your Solution Type is temporarily
unavailable. If possible, please use
another Solution Type.
10400 Transaction refused because
of an invalid argument. See
additional error messages for
details.
OrderTotal is missing.
10401 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Order total is invalid.
10402 Authorization only is not
allowed for merchant.
This merchant account is not
permitted to set PaymentAction to
Authorization. Please contact
Customer Service.
10404 Transaction refused because
of an invalid argument. See
additional error messages for
details.
ReturnURL is missing.
10405 Transaction refused because
of an invalid argument. See
additional error messages for
details.
CancelURL is missing.
10407 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Invalid buyer email address
(BuyerEmail).
10409 You’re not authorized to
access this info.
Express Checkout token was issued
for a merchant account other than
yours.
10410 Invalid token Invalid token.
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 213
API Error Codes
SetExpressCheckout API Errors A
10411 This Express Checkout
session has expired.
This Express Checkout session has
expired. Token value is no longer
valid.
If you receive this error, you
must return your buyer to
PayPal to approve the use of
PayPal again. Display an error
message to inform the buyer
that the transaction expired,
and provide a button to return
to PayPal. In this situation, you
are effectively restarting the
entire checkout process. (Do
not reuse the expired token
value on
SetExpressCheckout
request.) However, because
you already know the final
OrderTotal, be sure to
update the value for that
element if appropriate. You
might also want to update the
values for ReturnURL and
CancelURL, if necessary.
10412 Duplicate invoice Payment has already been made for
this InvoiceID.
PayPal checks that
InvoiceID values are unique
for any particular merchant. If
you send an InvoiceID value
already associated with another
transaction in the PayPal
system, PayPal returns error
code 10412.
You might not be able to
correct this error during an
actual checkout. If you receive
this error, research why it
might occur and modify your
implementation of Express
Checkout to ensure that you
generate unique invoice
identification numbers.
10413 Transaction refused because
of an invalid argument. See
additional error messages for
details
The totals of the cart item amounts
do not match order amounts.
If you receive this error, be
sure the total of the payment
detail item parameters, such as
ItemTotal, HandlingTotal,
TaxTotal, and so forth add up
to the order total.
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
214 August 2012 Name-Value Pair API Developer Guide
10415 Transaction refused because
of an invalid argument. See
additional error messages for
details.
A successful transaction has already
been completed for this token.
PayPal allows a token only
once for a successful
transaction.
If you determine that your
buyers are clicking your “Place
Order” button twice, PayPal
recommends that you disable
the button after your buyer has
clicked it.
10418 Transaction refused because
of an invalid argument. See
additional error messages for
details
The currencies of the shopping cart
amounts must be the same.
10425 Express Checkout has been
disabled for this merchant.
Express Checkout has been disabled
for this merchant. Please contact
Customer Service.
10426 Transaction refused because
of an invalid argument. See
additional error messages for
details
Item total is invalid.
10427 Transaction refused because
of an invalid argument. See
additional error messages for
details
Shipping total is invalid.
10428 Transaction refused because
of an invalid argument. See
additional error messages for
details
Handling total is invalid.
10429 Transaction refused because
of an invalid argument. See
additional error messages for
details
Tax total is invalid.
10430 Transaction refused because
of an invalid argument. See
additional error messages for
details
Item amount is missing.
10431 Transaction refused because
of an invalid argument. See
additional error messages for
details
Item amount is invalid.
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 215
API Error Codes
SetExpressCheckout API Errors A
10432 Transaction refused because
of an invalid argument. See
additional error messages for
details
Invoice ID value exceeds maximum
allowable length.
10433 Transaction refused because
of an invalid argument. See
additional error messages for
details
Value of Order Description has been
truncated.
10434 Transaction refused because
of an invalid argument. See
additional error messages for
details
Value of Custom element has been
truncated.
10436 Transaction refused because
of an invalid argument. See
additional error messages for
details.
PageStyle value exceeds maximum
allowable length.
10437 Transaction refused because
of an invalid argument. See
additional error messages for
details.
cpp-header-image value exceeds
maximum allowable length.
10438 Transaction refused because
of an invalid argument. See
additional error messages for
details.
cpp-header-image value exceeds
maximum allowable length.
10439 Transaction refused because
of an invalid argument. See
additional error messages for
details.
cpp-header-image value exceeds
maximum allowable length.
10440 Transaction refused because
of an invalid argument. See
additional error messages for
details.
cpp-header-image value exceeds
maximum allowable length.
10441 Transaction refused because
of an invalid argument. See
additional error messages for
details
The NotifyURL element value
exceeds maximum allowable length.
10442 ButtonSource value
truncated.
The ButtonSource element value
exceeds maximum allowable length.
10446 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Sale is only allowed PaymentAction.
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
216 August 2012 Name-Value Pair API Developer Guide
10457 Error occurred in
communicating to eBay
eBay API creation error
10458 Error occurred in
communicating to eBay
eBay API unknown failure
10459 Error occurred in
communicating to eBay
eBay API failure
10460 Error occurred in
communicating to eBay
Parsing error
10461 Error occurred in
communicating to eBay
Item number invalid, removed, or
unavailable
10462 Error occurred in
communicating to eBay
Order not found
10463 Error occurred in
communicating to eBay
eBay user password incorrect
10464 Error occurred in
communicating to eBay
Item ID and Transaction ID
mismatch
10465 Error occurred in
communicating to eBay
eBay user invalid
10467 Error occurred in
communicating to eBay
Duplicate Item ID
10468 Transaction refused because
of an invalid argument. See
additional error messages for
details
Duplicate Order ID
10469 PaymentAction of Order
Temporarily Unavailable
Express Auctions is unavailable
10470 Wowo flag is off for
ExpressO feature
Solution Type passed as Sole while
ExpressO feature is turned off
10471 Transaction refused because
of an invalid argument. See
additional error messages for
details
ReturnURL is missing
10472 Transaction refused because
of an invalid argument. See
additional error messages for
details
CancelURL is missing
10473 Error occurred in
communicating to eBay
Multiple Order IDs are not supported
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 217
API Error Codes
SetExpressCheckout API Errors A
10474 Invalid Data This transaction cannot be processed.
The country code in the shipping
address must match the buyer's
country of residence
10475 Transaction refused because
of an invalid argument. See
additional error messages for
details
This transaction cannot be completed
with PaymentAction of Sale
10476 Invalid Data Maximum number of billing
agreements exceeded
10477 Invalid Data More than one billing agreement
specified for reference transaction
10478 Invalid Data Recurring payments profile
description must be provided if the
billing agreement type is recurring
payments
10479 Invalid Data Billing agreement types cannot be
mixed in the same request
10480 Invalid Data Invalid billing agreement type
10485 Payment not authorized Payment has not been authorized by
the user.
10537 Risk Control Country Filter
Failure
The transaction was refused because
the country was prohibited as a result
of your Country Monitor Risk
Control Settings.
10538 Risk Control Max Amount
Failure
The transaction was refused because
the maximum amount was excceeded
as a result of your Maximum
Amount Risk Control Settings.
10539 Payment declined by your
Risk Controls settings:
PayPal Risk Model.
Payment declined by your Risk
Controls settings: PayPal Risk
Model.
10725 Shipping Address Country
Error
There was an error in the Shipping
Address Country field
10727 Shipping Address1 Empty The field Shipping Address1 is
required
10728 Shipping Address City
Empty
The field Shipping Address City is
required
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
218 August 2012 Name-Value Pair API Developer Guide
10729 Shipping Address State
Empty
The field Shipping Address State is
required
10730 Shipping Address Postal
Code Empty
The field Shipping Address Postal
Code is required
10731 Shipping Address Country
Empty
The field Shipping Address Country
is required
10736 Shipping Address Invalid
City State Postal Code
A match of the Shipping Address
City, State, and Postal Code failed.
10800 Invalid Data Your request is too long. Check
URLs and other long strings.
11001 Exceeds maximum length. Value of NoteText element is
truncated.
11001 Exceeds maximum length. OtherPaymentMethodID exceeds
maximum length.
11001 Exceeds maximum length. OtherPaymentMethodLabel exceeds
maximum length.
11001 Exceeds maximum length. OtherPaymentMethodLabelDescripti
on exceeds maximum length.
11001 Exceeds maximum length. OtherPaymentMethodLongDescripti
on exceeds maximum length.
11001 Exceeds maximum length. OtherPaymentMethodLongDescripti
onTitle exceeds maximum length.
11001 Exceeds maximum length. OtherPaymentMethodIcon exceeds
maximum length.
11068 Seller restriction. All sellers restricted.
11547 Recurring payments
temporarily unavailable; try
again later
Recurring payments temporarily
unavailable.
11547 Permission denied. Permission Denied. You are not
authorized to do this kind of
transaction
11601 Request for billing address
failed
Billing address request is not enabled
for merchant
11602 Request for billing address
failed
Feature not yet available
11801 Invalid Data You cannot pass both new and
deprecated parameter address fields.
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 219
API Error Codes
SetExpressCheckout API Errors A
11802 Invalid Data You cannot pass both the new and
deprecated Custom parameter.
11803 Invalid Data You cannot pass both the new and
deprecated Invoice ID parameter.
11804 Invalid Data You cannot pass both the new and
deprecated order description.
11805 Invalid Data You cannot pass both the new and
deprecated order total or amount
parameters.
11806 Invalid Data You cannot pass both the new and
deprecated
ProfileAddressChangeDate
parameter.
11807 Invalid Data You cannot pass both the new and
deprecated ShippingMethod
parameter.
11810 Transaction refused because
of an invalid argument. See
additional error messages for
details
Invalid Insurance Amount.
11811 Transaction refused because
of an invalid argument. See
additional error messages for
details
Invalid Shipping Discount.
11812 Invalid Data The value of Description parameter
has been truncated.
11813 Transaction refused because
of an invalid argument. See
additional error messages for
details
Invalid callback URL.
Callback URL is wrong type Callback URL is wrong type; you
must use the HTTPS
Ensure that your callback URL
starts with https://.
11814 Invalid data Invalid value for AllowNote.
11815 Transaction refused because
of an invalid argument. See
additional error messages for
details
Item sales tax is invalid.
Callback options missing You must specify callback options
when you specify a callback URL
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
220 August 2012 Name-Value Pair API Developer Guide
Invalid callback timeout The callback timeout is is zero; you
must specify a longer timeout
Line items missing Line items are required when specify
a callback URL for flate rate
shipping options
Callback URL is too long The callback URL must not exceed
1,024 characters
Multiple default shipping
options specified
You can only specify one default
shipping option at a time
No default shipping option
specified
You must specify a default shipping
option
Invalid shipping total Invalid shipping total; it should equal
the shipping amount of the default
shipping option
Invalid shipping options Invalid shipping options; you must
specify a name and amount for each
shipping option
11821 Invalid shipping options Invalid shipping options; you must
specify a name and amount for each
shipping option type
11822 Multiple default shipping
options specified
More than one shipping option type
is marked as the default; you can
only specify one default shipping
option at a time
11823 No default shipping option
specified
You must specify one shipping
option type as the default
11824 Invalid callback timeout The callback timeout is zero; you
must specify a longer timeout value
11825 Flat-rate shipping options
are missing
Flat-rate shipping options are
missing; you must specify flat-rate
shipping options when you specify a
callback URL
11826 Invalid shipping total Invalid shipping total; it should equal
the shipping amount of the selected
shipping option
11827 Line items missing Line items missing; line items are
required when you specify a callback
URL for flat-rate shipping options
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 221
API Error Codes
SetExpressCheckout API Errors A
11828 Maximum amount of order
not specified
Maximum amount of order not
specified; you must specify the
estimated value of the order when
using a flat-rate shipping option
11829 Shipping total is missing Shipping total is missing; you must
specify a shipping total when using a
flat-rate shipping option
11830 Insurance amount is missing Insurance amount is missing; you
have offered insurance but have not
specified an amount.
11831 Callback URL is too long Callback URL is too long; it must not
exceed 1,024 characters
11832 Maximum amount of order
is less than itemized amounts
Maximum amount of order is less
than itemized amounts; the value of
all items, including handling,
shipping, tax, and insurance cannot
be greater than the maximum amount
of the order
12109 Option not supported. Seller blocks payments via eBay
checkout for all eBay items.
12124 Option not supported. Express Checkout not supported for
you.
12200 Buyer ID is not present. Buyer ID must be specified to
process an Immediate Payment item.
12201 Immediate Payment item
was not found.
The item specified is either not valid
or is not currently available for
purchase as an Immediate Payment
item.
Please check that the item is a
valid Immediate Payment item.
12202 More than one eBay item is
present.
Only one Immediate Payment item
can be paid for in a single PayPal
payment transaction.
12205 eBay Transaction ID and
eBay Order ID must be null.
Requests for eBay Immediate
Payment items should not contain
either eBay transaction ID or eBay
order ID. If the fields are present,
they should contain null values.
12207 Cart ID is required for
Immediate Payment item.
Cart ID is required for Immediate
Payment item.
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
SetExpressCheckout API Errors
A
222 August 2012 Name-Value Pair API Developer Guide
12208 eBay item amount does not
match Express Checkout
API item amount.
eBay item amount must match
Express Checkout API item amount.
13100 Parallel payments
functionality is not available
Parallel payments functionality is not
available
13101 Invalid Data Payment action of Order is only
supported for parallel payments
13102 Payment Request ID is
missing
Payment Request ID is mandatory
for parallel payments
13103 Duplicate Payment Request
ID passed
Payment Request ID must be unique
for parallel payments
13104 Transaction refused because
of an invalid argument. See
Additional error messages
for details.
Number of payment requests exceeds
maximum number of supported
requests.
13105 Invalid Data Billing Agreement is not supported
for parallel payments.
13106 Invalid Data You cannot pass both the new and
deprecated PaymentAction
parameter.
13108 Merchant is not eligible. Merchant is not eligible for parallel
payments.
13110 Multi Payments Sale is Not
allowed
Due to some technical diffculties the
Multi Payments for Sale is not
avaliable now please try again later.
13111 Mixed Payment action not
supported
The Payment Action passed should
be unique, mixed Payment Action
not supported
13114 Buyer Didn't Complete The Buyer returned without
completing the payment
13115 Seller ID Missing Seller ID is mandatory for parallel
payments
13116 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction is in progress for this
token.
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 223
API Error Codes
GetExpressCheckoutDetails API Errors A
GetExpressCheckoutDetails API Errors
GetExpressCheckoutDetails API Errors
Error
Code Short Message Long Message Correcting This Error...
10001 Internal Error Internal Error
10001 Internal Error Transaction failed due to internal error
10001 ButtonSource value
truncated.
The transaction could not be loaded
10001 ButtonSource value
truncated.
The transaction could not be loaded
10003 Missing argument. OtherPaymentMethodID is missing.
10003 Missing argument. OtherPaymentMethodLabel is missing.
10003 Missing argument. OtherPaymentMethodType is missing.
10003 Missing argument. One or more of these giropay URLs is
missing: giropaySuccessURL,
giropayCancelURL,
BanktxnPendingURL.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Transaction refused because of an
invalid argument. See additional error
messages for details.
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction id is not valid
10004 Invalid transaction type You can not get the details for this type
of transaction
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction could not be loaded
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction id is not valid
10007 Permission denied You do not have permission to make
this API call
10007 Permission denied You do not have permission to get the
details of this transaction
API Error Codes
DoExpressCheckoutPayment API Errors
A
224 August 2012 Name-Value Pair API Developer Guide
DoExpressCheckoutPayment API Errors
DoExpressCheckoutPayment API Errors
10007 Permission denied You do not have permission to make
this API call
10408 Express Checkout token is
missing.
Express Checkout token is missing.
10409 You’re not authorized to
access this info.
Express Checkout token was issued for
a merchant account other than yours.
10410 Invalid token Invalid token.
10411 This Express Checkout
session has expired.
This Express Checkout session has
expired. Token value is no longer valid.
13112 Cannot Pay Seller. The Buyer will not be able to Pay the
seller for this transaction
13116 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction is in progress for this
token.
Error
Code Short Message Long Message Correcting This Error...
10001 Internal Error Transaction failed due to
internal error
10001 Internal Error Warning an internal error has
occurred. The transaction id
may not be correct
10001 ButtonSource value
truncated.
The transaction could not be
loaded
10001 Internal Error Internal Error
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Transaction refused because of
an invalid argument. See
additional error messages for
details.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The transaction id is not valid
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 225
API Error Codes
DoExpressCheckoutPayment API Errors A
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid item URL.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
SellerRegistrationDate is
invalid.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
overall positive count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
overall negative count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
total positive count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
total negative count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
recent positive count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay seller feedback
recent negative count.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay item transaction
date.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay item buyer
protection type.
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
DoExpressCheckoutPayment API Errors
A
226 August 2012 Name-Value Pair API Developer Guide
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid eBay item payment
hold risk.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Multiple eBay order IDs not
allowed.
10007 Permission denied You do not have permissions to
make this API call
10406 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The PayerID value is invalid.
10408 Express Checkout token is
missing.
Express Checkout token is
missing.
10409 You’re not authorized to
access this info.
Express Checkout token was
issued for a merchant account
other than yours.
10410 Invalid token Invalid token.
10411 This Express Checkout
session has expired.
This Express Checkout session
has expired. Token value is no
longer valid.
10412 Duplicate invoice Payment has already been
made for this InvoiceID.
10413 Transaction refused
because of an invalid
argument. See additional
error messages for details
The totals of the cart item
amounts do not match order
amounts.
If you receive this error, be sure the
total of the payment detail item
parameters, such as ItemTotal,
HandlingTotal, TaxTotal, and so forth
add up to the order total.
10414 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The amount exceeds the
maximum amount for a single
transaction.
10415 Transaction refused
because of an invalid
argument. See additional
error messages for details.
A successful transaction has
already been completed for this
token.
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 227
API Error Codes
DoExpressCheckoutPayment API Errors A
10416 Transaction refused
because of an invalid
argument. See additional
error messages for details.
You have exceeded the
maximum number of payment
attempts for this token.
10417 Transaction cannot
complete.
The transaction cannot
complete successfully. Instruct
the customer to use an
alternative payment method.
Instruct the buyer that PayPal is unable
to process the payment and redisplay
alternative payment methods with
which the buyer can pay.
10418 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The currencies of the shopping
cart amounts must be the same.
10419 Express Checkout
PayerID is missing.
Express Checkout PayerID is
missing.
10420 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Express Checkout
PaymentAction is missing.
10421 This Express Checkout
session belongs to a
different customer.
This Express Checkout session
belongs to a different customer.
Token value mismatch.
Verify that your programs are properly
associating the Tokens and PayerIDs.
10422 Customer must choose
new funding sources.
The customer must return to
PayPal to select new funding
sources.
10424 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Shipping address is invalid. If you receive this error message,
PayPal recommends that you return
your buyer to PayPal to review and
approve new valid funding sources.
Although this error is rare, you should
consider trapping the error to display a
message to the buyer describing what
happened, along with a button or
hyperlink to return to PayPal.
10426 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item total is invalid.
10427 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Shipping total is invalid.
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
DoExpressCheckoutPayment API Errors
A
228 August 2012 Name-Value Pair API Developer Guide
10428 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Handling total is invalid.
10429 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Tax total is invalid.
10431 Item amount is invalid. Item amount is invalid.
10432 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invoice ID value exceeds
maximum allowable length.
10433 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Value of OrderDescription
element has been truncated.
10434 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Value of Custom element has
been truncated.
10435 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The customer has not yet
confirmed payment for this
Express Checkout session.
10441 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The NotifyURL element value
exceeds maximum allowable
length.
10442 ButtonSource value
truncated.
The ButtonSource element
value exceeds maximum
allowable length.
10443 Transaction refused
because of an invalid
argument. See additional
error messages for details.
This transaction cannot be
completed with
PaymentAction of Order.
10444 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The transaction currency
specified must be the same as
previously specified.
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 229
API Error Codes
DoExpressCheckoutPayment API Errors A
10445 This transaction cannot be
processed at this time.
Please try again later.
This transaction cannot be
processed at this time. Please
try again later.
10446 Unconfirmed email A confirmed email is required
to make this API call.
10474 Invalid Data This transaction cannot be
processed. The country code in
the shipping address must
match the buyer’s country of
residence.
The buyer selects the country of
residence when they sign up for their
PayPal account. The country of
residence displays after the dash in the
title on the Account Overview page.
10481 Transaction refused
because of an invalid
argument. See additional
error messages for details.
PaymentAction of
Authorization is not allowed
with Unilateral and Non-
Credentialed authentication.
10486 This transaction couldn't
be completed.
This transaction couldn't be
completed. Please redirect your
customer to PayPal.
Redirect the buyer back to PayPal using
the original token so that the customer
can use or add a new funding
instrument.
10482 Transaction refused
because of an invalid
argument. See additional
error messages for details.
PaymentAction of Order is not
allowed with Unilateral and
Non-Credentialed
authentication.
10537 Risk Control Country
Filter Failure
The transaction was refused
because the country was
prohibited as a result of your
Country Monitor Risk Control
Settings.
10538 Risk Control Max Amount
Failure
The transaction was refused
because the maximum amount
was excceeded as a result of
your Maximum Amount Risk
Control Settings.
10539 Payment declined by your
Risk Controls settings:
PayPal Risk Model.
Payment declined by your Risk
Controls settings: PayPal Risk
Model.
10725 Shipping Address Country
Error
There was an error in the
Shipping Address Country
field
10727 Shipping Address1 Empty The field Shipping Address1 is
required
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
DoExpressCheckoutPayment API Errors
A
230 August 2012 Name-Value Pair API Developer Guide
10728 Shipping Address City
Empty
The field Shipping Address
City is required
10729 Shipping Address State
Empty
The field Shipping Address
State is required
10730 Shipping Address Postal
Code Empty
The field Shipping Address
Postal Code is required
10731 Shipping Address Country
Empty
The field Shipping Address
Country is required
10736 Shipping Address Invalid
City State Postal Code
A match of the Shipping
Address City, State, and Postal
Code failed.
11001 Exceeds maximum length. Value of NoteText element is
truncated.
11610 Payment Pending your
review in Fraud
Management Filters
Payment Pending your review
in Fraud Management Filters
11611 Transaction blocked by
your settings in FMF
Transaction blocked by your
settings in FMF
11612 Could not process your
request to accept/deny the
transaction
Could not process your request
to accept/deny the transaction
11820 Transaction refused
because of an invalid
argument. See additional
error messages for details
Invalid Order URL.
Invalid shipping amount Invalid shipping amount; it
should equal the shipping
amount of the selected
shipping option
Invalid shipping options Invalid shipping options; you
must specify a name and
amount for each shipping
option
11821 Invalid shipping options Invalid shipping options; you
must specify a name and
amount for each shipping
option type
11826 Invalid shipping total Invalid shipping total; it should
equal the shipping amount of
the selected shipping option
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 231
API Error Codes
DoExpressCheckoutPayment API Errors A
12125 PP incentive no longer
available.
There's a problem with the
redemption code(s) you
entered and can't be used at this
time. Your payment has not
been processed. Please go back
to PayPal so that the code(s)
can be removed, your order
total can be updated and then
you'll be able to complete
checkout.
12126 Payment could not be
processed at this time.
Incentive temporarily
unavailable.
We're having problems
processing redemption codes at
this time. Your payment has
not been processed. You can
try to check out again at a later
time or complete your payment
without the discount applied.
12201 Immediate Payment item
was not found.
The item specified is either not
valid or is not currently
available for purchase as an
Immediate Payment item.
Please check that the item is a valid
Immediate Payment item.
12203 Payment rolled back
because of pending item.
Payment was not created
because it would have been in a
pending state, which is
unacceptable for Immediate
Payment items.
12204 Transaction reversed. Error occurred causing
transaction reversal.
12206 The value of
PaymentAction must be
Sale for Immediate
Payment item.
Order and Authorization are
not acceptable values for
PaymentAction when the item
is an Immediate Payment
12207 Cart ID is required for
Immediate Payment item.
Cart ID is required for
Immediate Payment item.
12208 eBay item amount does
not match Express
Checkout API item
amount.
eBay item amount does not
match Express Checkout API
item amount.
13100 Parallel payments
functionality is not
available
Parallel payments functionality
is not available
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
DoExpressCheckoutPayment API Errors
A
232 August 2012 Name-Value Pair API Developer Guide
13101 Invalid Data Payment action of Order is
only supported for parallel
payments
13102 Payment Request ID is
missing
Payment Request ID is
mandatory for parallel
payments
13103 Duplicate Payment
Request ID passed
Payment Request ID must be
unique for parallel payments
13104 Transaction refused
because of an invalid
argument. See Additional
error messages for details.
Number of payment requests
exceeds maximum number of
supported requests.
13106 Invalid Data You cannot pass both the new
and deprecated PaymentAction
parameter.
13107 Parallel payments partially
successful.
One or more payment requests
failed. Check individual
payment responses for more
information.
13110 Multi Payments Sale is
Not allowed
Due to some technical
diffculties the Multi Payments
for Sale is not avaliable now
please try again later.
13111 Mixed Payment action not
supported
The Payment Action passed
should be unique, mixed
Payment Action not supported
13113 Buyer Cannot Pay. The Buyer cannot pay with
PayPal for this transaction.
13115 Seller ID Missing Seller ID is mandatory for
parallel payments
13116 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The transaction is in progress
for this token.
13751 Could not retrieve the
original successful
response.
Transaction completed
successfully, but could not
retrieve the original successful
response.
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 233
API Error Codes
Authorization and Capture API Errors A
Authorization and Capture API Errors
Authorization and Capture API Error Messages
Error
Code
Short
Message Long Message
Returned By API
Call...
Correcting This
Error...
10001 Internal Error Internal Error
10001 Internal Error Transaction failed due to
internal error
10004 Internal Error Invalid argument
10007 Permission
denied
You do not have
permissions to make this
API call
10009 Transaction
refused
Account is locked or
inactive
Retry the request at a
later time or close order.
10010 Transaction
refused because
of an invalid
argument. See
additional error
messages for
details.
Invalid argument
10202 Exceed max Transaction would
exceed user’s monthly
maximum
DoAuthorization
DoCapture
10600 Authorization
voided.
Authorization is voided. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the order or
authorization.
10601 Authorization
expired.
Authorization has
expired.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the order or
authorization.
10602 Authorization
completed.
Authorization has already
been completed.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the order or
authorization.
10603 The buyer is
restricted.
The buyer account is
restricted.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Contact the buyer.
API Error Codes
Authorization and Capture API Errors
A
234 August 2012 Name-Value Pair API Developer Guide
10604 Authorization
must include
both buyer and
seller.
Authorization transaction
cannot be unilateral. It
must include both buyer
and seller to make an
auth.
DoAuthorization Review the order to
ensure customer and
seller are both PayPal
members.
10605 Unsupported
currency.
Currency is not
supported.
DoAuthorization
DoCapture
Retry the request with a
PayPal-supported
currency.
10606 Buyer cannot
pay.
Transaction rejected,
please contact the buyer.
DoAuthorization
DoCapture
DoReauthorization
Contact the buyer.
10607 Auth&Capture
unavailable.
Authorization & Capture
feature unavailable.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Contact PayPal Customer
Service.
10608 Funding source
missing.
The funding source is
missing.
DoAuthorization
DoCapture
DoReauthorization
Contact the buyer.
10609 Invalid
transactionID.
Transaction id is invalid. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Check the validity of the
authorization ID and
reattempt the request.
10610 Amount limit
exceeded.
Amount specified
exceeds allowable limit.
DoAuthorization
DoCapture
DoReauthorization
Reattempt the request
with a lower amount.
10611 Not enabled. Authorization & Capture
feature is not enabled for
the merchant. Contact
customer service.
DoAuthorization
DoCapture
DoReauthorization
Contact PayPal Customer
Service.
10612 No more
settlement.
Maxmimum number of
allowable settlements has
been reached. No more
settlement for the
authorization.
DoCapture Close the order.
10613 Currency
mismatch.
Currency of capture must
be the same as currency
of authorization.
DoCapture Ensure that the currencies
are the same, and retry
the request.
10614 Cannot void
reauth.
You can void only the
original authorization,
not a reauthorization.
DoVoid Void the authorization.
Error
Code
Short
Message Long Message
Returned By API
Call...
Correcting This
Error...
Name-Value Pair API Developer Guide August 2012 235
API Error Codes
Authorization and Capture API Errors A
10615 Cannot reauth
reauth.
You can reauthorize only
the original authorization,
not a reauthorization.
DoReauthorization Capture the
reauthorization.
10616 Maximum
number of
reauthorization
allowed for the
auth is reached.
Maximum number of
reauthorization allowed
for the auth is reached.
DoReauthorization Capture or close the
authorization.
10617 Reauthorization
not allowed.
Reauthorization is not
allowed inside honor
period.
DoReauthorization Capture the authorization
or reauthorize outside of
honor period.
10618 Transaction
already voided
or expired.
Transaction has already
been voided or expired.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the order or
authorization.
10619 Invoice ID value
exceeds
maximum
allowable
length.
Invoice ID value exceeds
maximum allowable
length.
DoCapture Check the length of the
invoice ID and reattempt
the request.
10620 Order has
already been
voided, expired,
or completed.
Order has already been
voided, expired, or
completed.
DoAuthorization
DoCapture
DoVoid
Close this order.
10621 Order has
expired.
Order has expired. DoAuthorization
DoCapture
DoVoid
Close this order.
10622 Order is voided. Order is voided. DoAuthorization
DoCapture
DoVoid
Close this order.
10623 Maximum
number of
authorization
allowed for the
order is reached.
Maximum number of
authorization allowed for
the order is reached.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Capture this order.
10624 Duplicate
invoice
Payment has already
been made for this
Invoice ID.
DoAuthorization Review the invoice ID
and reattempt the request.
Error
Code
Short
Message Long Message
Returned By API
Call...
Correcting This
Error...
API Error Codes
Authorization and Capture API Errors
A
236 August 2012 Name-Value Pair API Developer Guide
10625 Transaction
refused because
of an invalid
argument. See
additional error
messages for
details.
The amount exceeds the
maximum amount for a
single transaction.
DoAuthorization
DoCapture
DoReauthorization
Reattempt the request
with a lower amount.
10626 Risk Transaction refused due
to risk model.
DoAuthorization
DoCapture
DoReauthorization
Contact the buyer.
10627 Transaction
refused because
of an invalid
argument. See
additional error
messages for
details.
The invoice ID field is
not supported for basic
authorizations.
DoAuthorization
DoReauthorization
DoVoid
The Invoice ID field can
be used only with
DoCapture.
10628 This transaction
cannot be
processed at this
time. Please try
again later.
This transaction cannot
be processed at this time.
Please try again later.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Retry the request at a
later time.
10629 Reauthorization
not allowed.
Reauthorization is not
allowed for this type of
authorization.
DoReauthorization Use DoAuthorization to
authorize the order.
10630 Item amount is
invalid.
Item amount is invalid. DoAuthorization
DoCapture
Check the item amount to
ensure that it is not zero
or negative.
10631 Processor
Warning.
The authorization is
being processed.
DoAuthorization
11094 This
authorization
cannot be
voided,
reauthorized, or
captured against.
This authorization can
only be handled through
the marketplace which
created it. It cannot
directly be voided,
reauthorized, or captured
against.
13122 Transaction
refused.
Transaction violates
PayPal use
DoCapture
Error
Code
Short
Message Long Message
Returned By API
Call...
Correcting This
Error...
Name-Value Pair API Developer Guide August 2012 237
API Error Codes
GetTransactionDetails API Errors A
GetTransactionDetails API Errors
GetTransactionDetails API Errors
TransactionSearch API Errors
TransactionSearch API Errors
Error Code Short Message Long Message
10001 Internal Error Internal Error
10004 Transaction refused because of an
invalid argument. See additional
error messages for details.
Store ID is required if Terminal ID is specified.
Error
Code Short Message Long Message
10001 Internal Error Internal Error
10001 ButtonSource value
truncated.
The transaction could not be loaded
10003 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Start date is a required parameter
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Start date is invalid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
End date is invalid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Currency is not supported
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Transaction class is not supported
API Error Codes
TransactionSearch API Errors
A
238 August 2012 Name-Value Pair API Developer Guide
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Receipt id is not valid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Payer email is invalid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Auction item id is not valid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Receiver email is invalid
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
You can not search for a transaction id and a receipt id
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
Receiver can only be specified for payments you’ve received
10004 Transaction refused because
of an invalid argument. See
additional error messages for
details.
The transaction id is not valid
10007 Permission denied You do not have permission to search for this transaction
10007 Permission denied You do not have permission to make this API call
11002 Search warning The number of results were truncated. Please change your search
parameters if you wish to see all your results.
Error
Code Short Message Long Message
Name-Value Pair API Developer Guide August 2012 239
API Error Codes
RefundTransaction API Errors A
RefundTransaction API Errors
RefundTransaction API Errors
Error
Code Short Message Long Message Correcting This Error...
10001 Internal Error Internal Error
10001 Internal Error Warning an internal error has occurred.
The transaction id may not be correct
10001 Internal Error The transaction could not be loaded.
10002 Restricted account Account is restricted.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The partial refund amount must be a
positive amount
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
You can not specify a partial amount
with a full refund
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
A transaction id is required
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The transaction id is not valid
10007 Permission denied You do not have permission to refund
this transaction
10007 Permission denied You do not have permissions to make
this API call
API Error Codes
RefundTransaction API Errors
A
240 August 2012 Name-Value Pair API Developer Guide
10009 Transaction refused You do not have a verified ACH This error can be caused by
insufficient funds in your
PayPal balance to cover the
amount of the refund and either
of the following:
-Not having yet verified the
bank account associated
with your PayPal account
-Not having any bank
account associated with
your PayPal account
Be sure that you have sufficient
funds in your PayPal balance
and that you have verified the
associated bank account.
10009 Transaction refused The partial refund amount must be less
than or equal to the original transaction
amount
10009 Transaction refused The partial refund amount must be less
than or equal to the remaining amount
10009 Transaction refused The partial refund amount is not valid
10009 Transaction refused Because a complaint case exists on this
transaction, only a refund of the full or
full remaining amount of the
transaction can be issued
10009 Transaction refused You are over the time limit to perform a
refund on this transaction
10009 Transaction refused Can not do a full refund after a partial
refund
10009 Transaction refused Account is locked or inactive
10009 Transaction refused The partial refund must be the same
currency as the original transaction
10009 Transaction refused This transaction has already been fully
refunded
10009 Transaction refused Account is restricted
10009 Transaction refused You can not refund this type of
transaction
10009 Transaction refused You can not do a partial refund on this
transaction
Error
Code Short Message Long Message Correcting This Error...
Name-Value Pair API Developer Guide August 2012 241
API Error Codes
RefundTransaction API Errors A
10009 Transaction refused The account for the counterparty is
locked or inactive
10009 Transaction refused This transaction already has a
chargeback filed
10009 Transaction refused You have not filled out the Direct Debit
Instruction
10011 Invalid transaction id value Transaction refused because of an
invalid transaction id value
10755 Unsupported currency Currency is not supported
11603 Conflict with prior request
with same Message
Submission ID.
One or more critical fields in the
request conflict with prior message
with the same Message Submission ID
(specified in MSGSUBID parameter).
11604 Request for Message
Submission ID already in
progress.
Request for the specified Message
Submission ID (specified in
MSGSUBID parameter) cannot be
started until the previous request
finishes.
Retry the request at a later
time.
11607 Duplicate request for
specified Message
Submission ID.
The specified Message Submission ID
(specified in MSGSUBID parameter) is
a duplicate; result parameters of the
original request are attached.
Retry the request at a later
time.
11996 Use Adaptive Payment
Refund API
To do a refund on an Adaptive Payment
transaction, please use the Adaptive
Payment Refund API
12302 Dispute Refund Not
Allowed
This transaction already has a PayPal
dispute filed
13513 Duplicate request for
specified Invoice ID.
The specified Invoice ID is a duplicate.
13531 Funding source provided
for this operation is not
supported
The funding source provided for this
operation is not supported. Please
provide a valid value.
13601 Refund cannot exceed the
transaction amount.
Refunds to users without PayPal
accounts cannot exceed the transaction
amount.
13602 Insufficient funds Refund failed due to insufficient funds
in your PayPal account
Error
Code Short Message Long Message Correcting This Error...
API Error Codes
MassPay API Errors
A
242 August 2012 Name-Value Pair API Developer Guide
MassPay API Errors
MassPay API Errors
Error
Code Short Message Long Message
10001 Invalid account number. The transaction failed as a result of an invalid credit card number.
Check the number or attempt with another card.
10001 Internal Error Internal Error
10001 Internal Error The transaction could not be loaded
10001 ButtonSource value truncated. The transaction could not be loaded
10001 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The masspay receiver_type is not a recognizable type
10002 Account locked The user account is locked
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The number of input records is greater than maximum allowed
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The number of input records is less than or equal to zero
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The note string length exceeds the maximum limit of 4000
characters
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The amount is missing
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The currency is missing
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
Currency is not supported
Name-Value Pair API Developer Guide August 2012 243
API Error Codes
MassPay API Errors A
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The amount is not a valid number
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The amount exceeds the max limit of a single mass pay item
~1
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The amount is less than or equal to zero
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The unique id string length exceeds the maximum limit of 30
characters
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The unique id string contains a space as a character
10004 Transaction refused because of
an invalid argument. See
additional error messages for
details.
The transaction id is not valid
10007 Permission denied You do not have permissions to make this API call
10301 User not allowed The user is not allowed to send money through Mass Pay
10303 Restricted account Account is restricted
10304 Unconfirmed email The user account has unconfirmed email
10305 Limit Exceeded The user account needs to have its sending limit removed in order to
make a mass payment.
10306 Limit Exceeded The user’s international account needs to have its sending limit
removed in order to make a mass payment
10307 Receive only account The user account is receive only and therefore cannot send payments
out
10308 Masspay server configuration
error
There is some configuration error
10309 Masspay server unavailable The mass pay server is unavailable
10310 Unable to create payment Unable to create payments for masspay
Error
Code Short Message Long Message
API Error Codes
Recurring Payments Errors
A
244 August 2012 Name-Value Pair API Developer Guide
Recurring Payments Errors
The following table lists errors for the following APIs that handle recurring payments profiles:
-CreateRecurringPaymentsProfile
-GetRecurringPaymentsProfileDetails
-ManageRecurringPaymentsProfileStatus
-UpdateRecurringPaymentsProfile
-BillOutstandingAmount
Recurring Payments Errors
10311 Unable to submit payment Unable to submit payments for masspay
10312 Masspay server error The masspay server has reported errors
10313 Masspay Invalid Data The masspay input file includes invalid data
10314 Masspay input parse error The input to the masspay server is incorrect. Please make sure that
you are using a correctly formatted input.
10317 Masspay Invalid Email The masspay input file includes invalid Email
10320 Internal Error Internal Error
10321 Insufficient funds The account does not have sufficient funds to do this masspay
10327 Masspay Invalid UserID The masspay input file includes invalid UserID
Error
Code Short Message Long Message Additional Information
10001 Invalid account number The transaction failed as a result of
invalid credit card number. Check
the number or attempt with another
credit card.
10003 Missing argument Item name, amount and quantity
are required if item category is
provided.
Scenario: Merchant passes item
category as either Digital or
Physical but does not also pass
one of the following parameters:
name, amount, or quantity.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
You are not signed up to accept
payment for digitally delivered
goods.
Scenario: Merchant is not signed
up for digital goods but passes
item category as Digital.
Error
Code Short Message Long Message
Name-Value Pair API Developer Guide August 2012 245
API Error Codes
Recurring Payments Errors A
10004 Cart item calculation
mismatch.
Cart item calculation mismatch.
The regular non-trial billing period
amount is different than the sum of
the amounts for each item in the
cart.
Scenario: When the regular non-
trial billing period amount is
different than the sum of the
amounts for each item in the
cart.
10004 Tax calculation mismatch. Tax calculation mismatch. The tax
amount for the regular non-trial
billing period is different than the
sum of the tax for each item in the
cart.
Scenario: When the tax for the
regular non-trial billing period is
different than the sum of the tax
for each item in the cart.
10478 Invalid Data Recurring payments profile
description must be provided if the
billing agreement type is recurring
payments.
10501 Invalid Configuration This transaction cannot be
processed due to an invalid
merchant configuration.
Occurs when the billing
agreement is disabled or
inactive.
10502 Invalid Data This transaction cannot be
processed. Please use a valid credit
card.
The credit card used is expired.
10504 Invalid Data This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
The CVV provided is invalid.
The CVV is between 3-4 digits
long.
10505 Gateway Decline This transaction cannot be
processed.
The transaction was refused
because the AVS response
returned the value of N, and the
merchant account is not able to
accept such transactions.
10507 Invalid Configuration This transaction cannot be
processed. Please contact PayPal
Customer Service.
Your PayPal account is
restricted. Contact PayPal for
more information.
10508 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card expiration date.
The expiration date must be a
two-digit month and four-digit
year.
10509 Invalid Data This transaction cannot be
processed.
You must submit an IP address
of the buyer with each API call.
10510 Invalid Data The credit card type is not
supported. Try another card type.
The credit card type entered is
not currently supported by
PayPal.
Error
Code Short Message Long Message Additional Information
API Error Codes
Recurring Payments Errors
A
246 August 2012 Name-Value Pair API Developer Guide
10511 Invalid Data This transaction cannot be
processed.
The merchant selected an value
for the PaymentAction field that
is not supported.
10512 Invalid Data This transaction cannot be
processed. Please enter a first
name.
The first name of the buyer is
required for this merchant.
10513 Invalid Data This transaction cannot be
processed. Please enter a last
name.
The last name of the buyer is
required for this merchant.
10535 Gateway decline This transaction cannot be
processed. Please enter a valid
credit card number and type.
10548 Invalid Configuration This transaction cannot be
processed. The merchant’s account
is not able to process transactions.
The merchant account
attempting the transaction is not
a business account at PayPal.
Check your account settings.
10550 Invalid Configuration This transaction cannot be
processed.
Access to Direct Payment was
disabled for your account.
Contact PayPal for more
information.
10561 Invalid Data There’s an error with this
transaction. Please enter complete
billing address.
10565 Merchant country
unsupported
The merchant country is not
supported.
10709 Invalid Data There’s an error with this
transaction. Please enter an
address1 in the billing address.
There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.
10710 Invalid Data There’s an error with this
transaction. Please enter a city in
the billing address.
There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.
10711 Invalid Data There’s an error with this
transaction. Please enter your state
in the billing address.
There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.
10712 Invalid Data There’s an error with this
transaction. Please enter your five
digit postal code in the billing
address.
There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.
Error
Code Short Message Long Message Additional Information
Name-Value Pair API Developer Guide August 2012 247
API Error Codes
Recurring Payments Errors A
10713 Invalid Data There’s an error with this
transaction. Please enter a country
in the billing address.
There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.
10744 Invalid Data This transaction cannot be
processed. Please enter a valid
country code in the billing address.
There was a problem with a
particular field in the address.
The long error message will tells
you which field is invalid.
10748 Invalid Data This transaction cannot be
processed without a Credit Card
Verification Number.
The merchant’s configuration
requires a CVV to be entered,
but no CVV was provided with
this transaction. Contact PayPal
if you wish to change this
setting.
10751 Invalid Data There’s an error with this
transaction. Please enter a valid
state in the billing address.
The merchant provided an
address either in the United
States or Canada, but the state
provided is not a valid state in
either country.
10752 Gateway Decline This transaction cannot be
processed.
The transaction was declined by
the issuing bank, not PayPal. The
merchant should attempt another
card.
10760 Invalid Configuration This transaction cannot be
processed. The country listed for
your business address is not
currently supported.
The merchant’s country of
residence listed in their PayPal
account is not currently
supported to allow Direct
Payment transactions.
11089 Transaction Refused. Account is locked or inactive.
11501 Invalid merchant country The merchant’s country is
currently not supported
Missing token
11502 The token is missing or is
invalid
The token is missing or is invalid One or more subscription detail
fields are missing from the
request.
11503 Missing subscription details Missing subscription details One or more schedule detail
fields are missing from the
request.
11504 Missing schedule details Missing schedule details
11505 Start date should be greater
than current date
Subscription start date should be
greater than current date
Error
Code Short Message Long Message Additional Information
API Error Codes
Recurring Payments Errors
A
248 August 2012 Name-Value Pair API Developer Guide
11506 Invalid max failed
payments
Max failed payments, if supplied,
must be >= 0
11507 Invalid trial amount Trial amount must be >= 0
11508 Invalid trial total billing
cycles
Trial total billing cycles must be >
0
11509 Invalid trial billing period Trial billing period must be one of
Day, Week, Month, SemiMonth, or
Year
11510 Invalid trial amount Trial amount must be >= 0
11511 Invalid currency for trial
amount
This currency is currently not
supported for trial amount.
Currency must be USD.
11512 Invalid trial shipping
amount
Trial shipping amount must be >=
0
If a trial shipping amount is
supplied, it must be >= 0.
11513 Invalid currency for trial
shipping amount
This currency is currently not
supported for trial shipping amount
Currency must be USD.
11514 Invalid profile status The profile status is invalid.
11515 Invalid currency for trial tax
amount
This currency is currently not
supported for trial tax amount
Currency must be USD.
11516 Invalid billing frequency Billing Frequency must be > 0 and
be less than or equal to one year
The combination of billing
frequency and billing period
cannot exceed one year.
11517 Invalid total billing cycles Total billing cycles must be >= 0 (0
means continuous)
11518 Invalid billing period Billing period must be one of Day,
Week, Month, SemiMonth, or Year
11519 Invalid amount Bill amount must be greater than 0
11520 Invalid currency for amount This currency is currently not
supported for amount
Currency must be USD.
11521 Invalid shipping amount Shipping amount must be >= 0
11522 Invalid currency for
shipping amount
This currency is currently not
supported for shipping amount
Currency must be USD.
11523 Invalid tax amount Tax amount must be >= 0
11524 Invalid currency for tax
amount
This currency is currently not
supported for tax amount
Currency must be USD.
11531 Invalid profile status The profile status must be one of
(A)ctive, (C)ancelled, or e(X)pired
Error
Code Short Message Long Message Additional Information
Name-Value Pair API Developer Guide August 2012 249
API Error Codes
Recurring Payments Errors A
11543 Invalid payer country The payer’s country is currently
not supported
11544 Invalid period status The trial period status must be one
of (A)ctive or (C)ancelled
11545 Denied Payer’s account is denied
11546 Denied Merchant account is denied
11547 This feature is not available
at this time
Recurring payments feature is not
currently available; try again later
11548 Invalid currency code Invalid currency code, all currency
codes much match
11549 Start Date is required Subscription start date is required
11550 Start Date should be valid Subscription start date should be
valid
11551 Profile ID is missing from
the request
Profile ID is missing from the
request
11552 Invalid profile ID The profile ID is invalid
11553 Invalid action value
provided
Invalid action value provided
11554 Note is missing from the
request
Note is missing from the request
11555
11556 Invalid profile status for
cancel action; profile
should be active or
suspended
Invalid profile status for suspend
action; profile should be active
11557 Invalid profile status for
suspend action; profile
should be active
Invalid profile status for reactivate
action; profile should be suspended
11558 Invalid profile status for
reactivate action; profile
should be suspended
The activation type is invalid
11560 Invalid activation type The activation type is invalid
11561 Invalid initial amount The initial amount is invalid
11562 Invalid auto bill type The auto bill type is invalid
Error
Code Short Message Long Message Additional Information
API Error Codes
Recurring Payments Errors
A
250 August 2012 Name-Value Pair API Developer Guide
11564 The number of failed
payments should be greater
than the current number of
failed payments
The number of failed payments
should be greater than the current
number of failed payments
11567 The time of the update is
too close to the billing date
The time of the update is too close
to the billing date
11568 Invalid currency for
delinquent amount
Invalid currency for delinquent
amount
11569 Cannot increase delinquent
amount
Cannot increase delinquent amount
11570 The maximum number of
failed payments should be
greater than the current
number of failed payments
The maximum number of failed
payments should be greater than
the current number of failed
payments
11571 The total amount cannot
exceed 120% increment per
180 days
The total amount cannot exceed
120% increment per 180 days
11576 Bill amount is greater than
outstanding balance
Bill amount is greater than
outstanding balance
11577 Another outstanding
payment is scheduled
Another outstanding payment is
scheduled
11578 Bill outstanding amount not
processed because of
scheduled payment
Recurring payment scheduled
within 24 hours, so we are not
processing the bill outstanding
amount
11579 Payment is failing Payment is failing
11581 Invalid Data Profile description is invalid.
11582 No payment in queue No scheduled payment has been
found.
11583 DPRP feature is unavailable DPRP feature is unavailable
11584 Inactive profile Profile is not active
11585 Missing Token or buyer
credit card
Missing token or payment source
11586 DPRP is disabled DPRP is disabled for this
merchant.
11587 Billing Address is Partial Billing Address is Partial
Error
Code Short Message Long Message Additional Information
Name-Value Pair API Developer Guide August 2012 251
API Error Codes
SetCustomerBillingAgreement Errors A
SetCustomerBillingAgreement Errors
SetCustomerBillingAgreement Errors
11590 Profile update is not
required
Based on your input request,
profile already up to date.
11592 Subscription profiles are
not supported for recurring
payments
Subscription profiles are not
supported for recurring payments
13122 Transaction refused Transaction violates PayPal use
13701 Invalid Data Item Category value is invalid.
Only Digital or Physical are
allowed.
Scenario: When merchant passes
an item category value other than
Digital or Physical.
15004 Gateway Decline This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
Error
Code Short Message Long Message Additional Information
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid argument; BillingType
input field is set to None
10404 Transaction refused
because of an invalid
argument. See additional
error messages for details.
ReturnURL is missing. ReturnURL tag has no content.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid value for request billing
address parameter.
10405 Transaction refused
because of an invalid
argument. See additional
error messages for details.
CancelURL is missing. CancelURL tag has no content.
10407 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid buyer email address
(BuyerEmail).
Invalid BuyerEmail (badly
formatted or violates SMTP
protocol defined email address
format) or BuyerEmail is passed
as an empty tag.
Error
Code Short Message Long Message Additional Information
API Error Codes
SetCustomerBillingAgreement Errors
A
252 August 2012 Name-Value Pair API Developer Guide
10436 Transaction refused
because of an invalid
argument. See additional
error messages for details.
PageStyle value exceeds maximum
allowable length.
PageStyle tag is too long.
10437 Transaction refused
because of an invalid
argument. See additional
error messages for details.
cpp-header-image value exceeds
maximum allowable length.
cpp_header_image tag is too
long; maximum length is 127.
10438 Transaction refused
because of an invalid
argument. See additional
error messages for details.
cpp-header-border-color value
exceeds maximum allowable
length.
cpp_header_border_color tag is
too long; maximum length is 6.
10439 Transaction refused
because of an invalid
argument. See additional
error messages for details.
cpp-header-back-color value
exceeds maximum allowable
length.
cpp_header_back_color tag is
too long; maximum length is 6.
10440 Transaction refused
because of an invalid
argument. See additional
error messages for details.
cpp-payflow-color value exceeds
maximum allowable length.
cpp_payflow_color tag is too
long; maximum length is 6.
10471 Transaction refused
because of an invalid
argument. See additional
error messages for details.
ReturnURL is invalid. ReturnURL tag contains invalid
URL.
10472 Transaction refused
because of an invalid
argument. See additional
error messages for details.
CancelURL is invalid. CancelURL tag contains invalid
URL.
10476 Transaction refused
because of an invalid
argument. See additional
error messages for details.
10477 Transaction refused
because of an invalid
argument. See additional
error messages for details.
10485 Payment not authorized Payment has not been authorized
by the user.
11452 Merchant not enabled for
reference transactions
Merchant not enabled for reference
transactions
This merchant is not enabled for
Mark reference transaction.
Warning only.
Error
Code Short Message Long Message Additional Information
Name-Value Pair API Developer Guide August 2012 253
API Error Codes
GetBillingAgreementCustomerDetails Errors A
GetBillingAgreementCustomerDetails Errors
GetBillingAgreementCustomerDetails Errors
CreateBillingAgreement Errors
CreateBillingAgreement Errors
11453 Reference transactions
temporarily unavailable.
Reference transaction feature not
currently available; try again later
Feature not enabled because
system is running in standin
mode. Warning only.
11601 Request for billing address
failed
Billing address request is not
enabled for merchant
11602 Request for billing address
failed
Feature not yet available
Error
Code Short Message Long Message Additional Information
10408 Missing token Token is missing Token is missing.
10409 You’re not authorized to
access this info.
Express Checkout token was
issued for a merchant account
other than yours.
Token belongs to a different
merchant.
10410 Invalid token Invalid token Token is invalid.
10411 This Express Checkout
session has expired.
This Express Checkout session has
expired. Token value is no longer
valid.
Token expired.
Error
Code Short Message Long Message Additional Information
10408 Missing token Token is missing Token is missing.
10409 You’re not authorized to
access this info.
Express Checkout token was
issued for a merchant account
other than yours.
Token belongs to a different
merchant.
10410 Invalid token Invalid token Token is invalid.
10411 This Express Checkout
session has expired.
This Express Checkout session has
expired. Token value is no longer
valid.
Token expired.
Error
Code Short Message Long Message Additional Information
API Error Codes
UpdateBillingAgreement Errors
A
254 August 2012 Name-Value Pair API Developer Guide
UpdateBillingAgreement Errors
UpdateBillingAgreement Errors
11455 Buyer did not accept billing
agreement
Buyer did not accept billing
agreement
Buyer has not agreed to the
billing agreement.
11456 A successful Billing
Agreement has already
been created for this token.
Transaction refused because of an
invalid argument. See additional
error messages for details.
Token has already been used to
create a billing agreement.
10408 Missing token Token is missing Token is missing.
10409 You’re not authorized to
access this info.
Express Checkout token was
issued for a merchant account
other than yours.
Token belongs to a different
merchant.
10410 Invalid token Invalid token Token is invalid.
10411 This Express Checkout
session has expired.
This Express Checkout session has
expired. Token value is no longer
valid.
Token expired.
Error
Code Short Message Long Message Additional Information
10001 Internal Error Internal Error
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid argument; description field
or custom field is empty and the
status is active
Check the description and
custom fields of the billing
agreement. Either the description
or custom field is empty and the
status is active or the contents of
one of these fields exceeds the
maximum field length.
10201 Billing Agreement was
cancelled
Billing Agreement was cancelled Billing agreement has been
cancelled.
10204 User’s account is closed or
restricted
User’s account is closed or
restricted
10209 Disabled Preapproved Payments not
enabled.
Merchant pull is not enabled for
the country or merchant is not
enabled for merchant pull.
10209 Disabled Preapproved Payments not
enabled.
Account number mismatch
exists for the API caller and the
account the billing agreement
belongs to.
Error
Code Short Message Long Message Additional Information
Name-Value Pair API Developer Guide August 2012 255
API Error Codes
DoReferenceTransaction Errors A
DoReferenceTransaction Errors
All Reference Transactions-Related API Errors
10211 Invalid billing agreement
ID
Invalid transaction or billing
agreement ID; could not find
Billing Agreement in database
11451 Billing Agreement Id or
transaction Id is not valid
Billing Agreement Id or
transaction Id is not valid
ReferenceID field is empty.
11451 Billing Agreement Id or
transaction Id is not valid
Billing Agreement Id or
transaction Id is not valid
Reference id refers to an invalid
transaction.
11452 Merchant not enabled for
reference transactions
Merchant not enabled for reference
transactions
This merchant is not enabled for
Mark reference transaction.
Error
Code Short Message Long Message Additional Information
10001 Internal Error Internal Error
10002 Authentication/Authorizati
on Failed
10003 Missing argument Item name, amount and quantity
are required if item category is
provided.
Scenario: Merchant passes item
category as either Digital or
Physical but does not also pass
one of the following parameters:
name, amount, or quantity.
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
You are not signed up to accept
payment for digitally delivered
goods.
Scenario: Merchant is not signed
up for digital goods but passes
item category as Digital.
10004 Cart item calculation
mismatch.
Cart item calculation mismatch.
The regular non-trial billing period
amount is different than the sum of
the amounts for each item in the
cart.
Scenario: When the regular non-
trial billing period amount is
different than the sum of the
amounts for each item in the
cart.
10004 Tax calculation mismatch. Tax calculation mismatch. The tax
amount for the regular non-trial
billing period is different than the
sum of the tax for each item in the
cart.
Scenario: When the regular non-
trial billing period is different
than the sum of the tax for each
item in the cart.
Error
Code Short Message Long Message Additional Information
API Error Codes
DoReferenceTransaction Errors
A
256 August 2012 Name-Value Pair API Developer Guide
10004 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invalid payment type argument
10009 Transaction refused The account for the counterparty is
locked or inactive
Merchant is
locked/close/restricted.
10010 Invalid Invoice Non-ASCII invoice id is not
supported
Non-ASCII characters are used
in InvoiceID field.
10201 Agreement canceled Billing Agreement was cancelled Billing agreement is not active.
10202 Exceed max Transaction would exceed user’s
monthly maximum
Transaction would exceed the
monthly limit.
10203 Action required Transaction failed, action required
by user
10204 User’s account is closed or
restricted
User’s account is closed or
restricted
10205 Risk Transaction refused due to risk
model
10206 Duplicate Transaction was already processed
10207 Retry Transaction failed but user has
alternate funding source
Retry the transaction with an
alternate funding source.
10209 Disabled Preapproved Payments not
enabled.
Merchants is not enabled for
preapproved payments (PAP);
applies only to legacy PAP
billing agreements.
10210 No Funding Transaction failed because has no
funding sources
Payee has no funding sources.
10211 Invalid MP ID Invalid MP ID.
10212 Profile preference setting A profile preference is set to
automatically deny certain
transactions
A profile preference is set that
automatically denies this kind of
transaction.
10213 Invalid Soft Descriptor The soft descriptor passed in
contains invalid characters
10214 Soft descriptor format error.
10215 Soft Descriptor truncated The soft descriptor was truncated
10216 Confirmed address required Transaction refused because a
confirmed address is not available
Transaction refused because a
confirmed address is not
available.
Error
Code Short Message Long Message Additional Information
Name-Value Pair API Developer Guide August 2012 257
API Error Codes
DoReferenceTransaction Errors A
10400 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Order total is missing. TotalOrder amount is missing.
10401 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Order total is invalid. TotalOrder amount is invalid.
10402 Authorization only is not
allowed for merchant.
This merchant account is not
permitted to set PaymentAction? to
Authorization. Please contact
Customer Service.
Merchant is not eligible for auth
settlement.
10406 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The PayerID? value is invalid. Merchant account number is
invalid.
10412 Duplicate invoice Payment has already been made
for this InvoiceID?.
Payment already made for the
invoice.
10413 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The totals of the cart item amounts
do not match order amounts.
Total of cart items does not
match order total.
10414 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The amount exceeds the maximum
amount for a single transaction.
Amount exceeds the max
amount for a single txn.
10417 Transaction cannot
complete.
The transaction cannot complete
successfully. Instruct the customer
to use an alternative payment
method.
Account not associated with a
usable funding source.
10417 Transaction cannot
complete.
The transaction cannot complete
successfully. Instruct the customer
to use an alternative payment
method.
Credit card or Billing Agreement
is required to complete payment.
10418 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The currencies of the shopping cart
amounts must be the same.
Currencies in the shopping cart
must be the same.
10420 Transaction refused
because of an invalid
argument. See additional
error messages for details.
PaymentAction? tag is missing. PaymentAction? tag is missing.
Error
Code Short Message Long Message Additional Information
API Error Codes
DoReferenceTransaction Errors
A
258 August 2012 Name-Value Pair API Developer Guide
10426 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item total is invalid. ItemTotal amount is invalid.
10427 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Shipping total is invalid. ShippingTotal amount is invalid.
10428 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Handling total is invalid. HandlingTotal amount is invalid.
10429 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Tax total is invalid. TaxTotal amount is invalid.
10429 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item sales tax is invalid PaymentDetailsItem.Tax field is
invalid. Warning only; API
executes.
10430 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item amount is missing. PaymentDetailsItem.Amount
field is missing. Warning only;
API executes.
10431 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Item amount is invalid. PaymentDetailsItem.Amount
field is invalid. Warning only;
API executes.
10432 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Invoice ID value exceeds
maximum allowable length.
InvoiceID field is too long;
maximum length is 256.
10433 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Value of OrderDescription element
has been truncated.
OrderDescription field is too
long; maximum length is 127.
Warning only; API executes.
10434 Transaction refused
because of an invalid
argument. See additional
error messages for details.
Value of Custom element has been
truncated.
Custom field is too long;
maximum length is 256.
Warning only; API executes.
Error
Code Short Message Long Message Additional Information
Name-Value Pair API Developer Guide August 2012 259
API Error Codes
DoReferenceTransaction Errors A
10441 Transaction refused
because of an invalid
argument. See additional
error messages for details.
The NotifyURL element value
exceeds maximum allowable
length.
NotifyURL field is too long;
maximum length for notify URL
is 2048.
10442 ButtonSource value
truncated.
The ButtonSource element value
exceeds maximum allowable
length.
ButtonSource field is too long;
maximum length is 32. Warning
only; API executes.
10504 The cvv2 is invalid. This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
CVV2 field is invalid.
10527 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card number and type.
CreditCardNumber and/or
CreditCardType is invalid.
10537 Risk Control Country Filter
Failure
The transaction was refused
because the country was prohibited
as a result of your Country Monitor
Risk Control Settings.
Transaction refused due to
country monitor risk control.
10538 Risk Control Max Amount
Failure
The transaction was refused
because the maximum amount was
excused as a result of your
Maximum Amount Risk Control
Settings.
Transaction refused due to max
amount risk control.
10539 Payment declined by your
Risk Controls settings:
PayPal Risk Model.
Payment declined by your Risk
Controls settings: PayPal Risk
Model.
Transaction declined by Risk
Control settings: PayPal Risk
model.
10546 Gateway Decline This transaction cannot be
processed.
IP fraud models failed.
10560 Invalid Data The issue number of the credit card
is invalid.
IssueNumber is invalid.
10567 Invalid Data A Start Date or Issue Number is
required.
None of Start date or issue
number is specified (only applies
to Switch credit cards).
10600 Authorization voided Authorization voided.
10601 Authorization expired. Authorization has expired
10621 Order has expired. Order has expired.
10622 Order is voided. Order is voided.
10623 Maximum number of
authorization allowed for
the order is reached.
Maximum number of authorization
allowed for the order is reached.
Error
Code Short Message Long Message Additional Information
API Error Codes
DoReferenceTransaction Errors
A
260 August 2012 Name-Value Pair API Developer Guide
10725 Shipping Address Country
Error
There was an error in the Shipping
Address Country field
Shipping address error in
country field.
10727 Shipping Address1 Empty The field Shipping Address1 is
required
Shipping address error in
address1 field.
10728 Shipping Address City
Empty
The field Shipping Address City is
required
Shipping address error in city
field.
10729 Shipping Address State
Empty
The field Shipping Address State is
required
Shipping address error in state
field.
10730 Shipping Address Postal
Code Empty
The field Shipping Address Postal
Code is required
Shipping address error in postal
code.
10731 Shipping Address Country
Empty
The field Shipping Address
Country is required
Country code is empty in
shipping address.
10736 Shipping Address Invalid
City State Postal Code
A match of the Shipping Address
City, State, and Postal Code failed.
Match of shipping address, city,
state, and postal code failed.
10747 Invalid Data This transaction cannot be
processed without a valid IP
address.
IPAddress field is invalid.
10748 Invalid Data This transaction cannot be
processed without a Credit Card
Verification number.
CVV2 field is missing.
10755 Unsupported Currency. This transaction cannot be
processed due to an unsupported
currency.
11084 User does not have a good
funding source with which
to pay.
User does not have a good funding
source with which to pay.
Scenario: The credit card
associated with the account
could not be used and there is no
other funding source with which
to complete the transaction.
11091 The transaction was
blocked as it would exceed
the sending limit for this
buyer.
The transaction was blocked as it
would exceed the sending limit for
this buyer.
The transaction was declined by
PayPal. Please have the buyer
contact PayPal Customer
Service.
11302 Cannot pay self The transaction was refused
because you cannot send money to
yourself.
Cannot pay self. Merchant is
referencing own transaction.
11451 Billing Agreement Id or
transaction Id is not valid
Billing Agreement Id or
transaction Id is not valid
Invalid reference id.
Error
Code Short Message Long Message Additional Information
Name-Value Pair API Developer Guide August 2012 261
API Error Codes
DoReferenceTransaction Errors A
11451 Billing Agreement Id or
transaction Id is not valid
Billing Agreement Id or
transaction Id is not valid
Reference transaction is not
associated with a billing
agreement.
11451 Billing Agreement Id or
transaction Id is not valid
Billing Agreement Id or
transaction Id is not valid
Reference id either not found or
could not be decrypted.
11451 Billing Agreement Id or
transaction Id is not valid
Billing Agreement Id or
transaction Id is not valid
Reference id either not found or
could not be decrypted.
11452 Merchant not enabled for
reference transactions
Merchant not enabled for reference
transactions
This merchant is not enabled for
Mark reference transaction.
11453 Reference transactions
temporarily unavailable.
Reference transaction feature not
currently available; try again later
Feature wired off.
11453 Reference transactions
temporarily unavailable.
Reference transaction feature not
currently available; try again later
Feature not supported in standin.
11454 Warning: Could not send
email to the buyer
Warning: Could not send email to
the buyer
Failed to send email to buyer.
This error is not fatal and
generates a warning.
11459 Invalid Data The shipping address must match
the user’s address in the PayPal
account.
The shipping address on file
does not match the requested
shipping address.
11610 Payment Pending your
review in Fraud
Management Filters
Payment Pending your review in
Fraud Management Filters
11611 Transaction blocked by
your settings in FMF
Transaction blocked by your
settings in FMF
11612 Could not process your
request to accept/deny the
transaction
Could not process your request to
accept/deny the transaction
13122 Transaction refused Transaction violates PayPal Use
13701 Invalid Data Item Category value is invalid.
Only Digital or Physical are
allowed.
Scenario: When merchant passes
an item category value other than
Digital or Physical.
18014 Gateway Decline This transaction cannot be
processed.
This transaction cannot be
processed without a Credit Card
Verification number.
Error
Code Short Message Long Message Additional Information
API Error Codes
AddressVerify API Errors
A
262 August 2012 Name-Value Pair API Developer Guide
AddressVerify API Errors
AddressVerify API Errors
ManagePendingTransactionStatus API Errors
ManagePendingTransactionStatus API Errors
Error Code Short Message Long Message
10004 Transaction refused because
of an invalid argument. See
additional error messages
for details.
Invalid email format.
10004 Transaction refused because
of an invalid argument. See
additional error messages
for details.
Invalid street format
10004 Transaction refused because
of an invalid argument. See
additional error messages
for details.
Invalid zip format
10009 The API is disabled. The Address API is currently disabled
Error Code Short Message Long Message
11614 Could not process your request
to accept/deny the transaction
Could not process your request to accept/deny the transaction
11614 The transaction has already
been Accepted/Denied and the
status cannot be changed
The transaction has already been Accepted/Denied and the
status cannot be changed
Name-Value Pair API Developer Guide August 2012 263
BCountries and Regions
Supported by PayPal
PayPal uses 2-character IS0-3166-1 codes for specifying countries and regions that are
supported in fields and variables. Countries marked with an asterisk ( * ) are not supported for
PayPal Payments Pro and Virtual Terminal.
Country or Region Country or Region Code
ÅLAND ISLANDS AX
ALBANIA AL
ALGERIA * DZ *
AMERICAN SAMOA AS
ANDORRA AD
ANGUILLA AI
ANTARCTICA * AQ *
ANTIGUA AND BARBUDA AG
ARGENTINA AR
ARMENIA AM
ARUBA AW
AUSTRALIA AU
AUSTRIA AT
AZERBAIJAN AZ
BAHAMAS BS
BAHRAIN BH
BANGLADESH BD
BARBADOS BB
BELGIUM BE
BELIZE BZ
BENIN BJ
BERMUDA BM
BHUTAN BT
BOSNIA-HERZEGOVINA BA
Countries and Regions Supported by PayPal
B
264 August 2012 Name-Value Pair API Developer Guide
BOTSWANA BW
BOUVET ISLAND * BV *
BRAZIL BR
BRITISH INDIAN OCEAN TERRITORY * IO *
BRUNEI DARUSSALAM BN
BULGARIA BG
BURKINA FASO BF
CANADA CA
CAPE VERDE CV
CAYMAN ISLANDS KY
CENTRAL AFRICAN REPUBLIC * CF *
CHILE CL
CHINA CN
CHRISTMAS ISLAND * CX *
COCOS (KEELING) ISLANDS CC
COLOMBIA CO
COOK ISLANDS CK
COSTA RICA CR
CYPRUS CY
CZECH REPUBLIC CZ
DENMARK DK
DJIBOUTI DJ
DOMINICA DM
DOMINICAN REPUBLIC DO
ECUADOR EC
EGYPT EG
EL SALVADOR SV
ESTONIA EE
FALKLAND ISLANDS (MALVINAS) FK
FAROE ISLANDS FO
FIJI FJ
Country or Region Country or Region Code
Name-Value Pair API Developer Guide August 2012 265
Countries and Regions Supported by PayPal B
FINLAND FI
FRANCE FR
FRENCH GUIANA GF
FRENCH POLYNESIA PF
FRENCH SOUTHERN TERRITORIES TF
GABON GA
GAMBIA GM
GEORGIA GE
GERMANY DE
GHANA GH
GIBRALTAR GI
GREECE GR
GREENLAND GL
GRENADA GD
GUADELOUPE GP
GUAM GU
GUERNSEY GG
GUYANA GY
HEARD ISLAND AND MCDONALD ISLANDS * HM *
HOLY SEE (VATICAN CITY STATE) VA
HONDURAS HN
HONG KONG HK
HUNGARY HU
ICELAND IS
INDIA IN
INDONESIA ID
IRELAND IE
ISLE OF MAN IM
ISRAEL IL
ITALY IT
JAMAICA JM
Country or Region Country or Region Code
Countries and Regions Supported by PayPal
B
266 August 2012 Name-Value Pair API Developer Guide
JAPAN JP
JERSEY JE
JORDAN JO
KAZAKHSTAN KZ
KIRIBATI KI
KOREA, REPUBLIC OF KR
KUWAIT KW
KYRGYZSTAN KG
LATVIA LV
LESOTHO LS
LIECHTENSTEIN LI
LITHUANIA LT
LUXEMBOURG LU
MACAO MO
MACEDONIA MK
MADAGASCAR MG
MALAWI MW
MALAYSIA MY
MALTA MT
MARSHALL ISLANDS MH
MARTINIQUE MQ
MAURITANIA MR
MAURITIUS MU
MAYOTTE YT
MEXICO MX
MICRONESIA, FEDERATED STATES OF FM
MOLDOVA, REPUBLIC OF MD
MONACO MC
MONGOLIA MN
MONTENEGRO ME
MONTSERRAT MS
Country or Region Country or Region Code
Name-Value Pair API Developer Guide August 2012 267
Countries and Regions Supported by PayPal B
MOROCCO MA
MOZAMBIQUE MZ
NAMIBIA NA
NAURU NR
NEPAL * NP *
NETHERLANDS NL
NETHERLANDS ANTILLES AN
NEW CALEDONIA NC
NEW ZEALAND NZ
NICARAGUA NI
NIGER NE
NIUE NU
NORFOLK ISLAND NF
NORTHERN MARIANA ISLANDS MP
NORWAY NO
OMAN OM
PALAU PW
PALESTINE PS
PANAMA PA
PARAGUAY PY
PERU PE
PHILIPPINES PH
PITCAIRN PN
POLAND PL
PORTUGAL PT
PUERTO RICO PR
QATAR QA
REUNION RE
ROMANIA RO
RUSSIAN FEDERATION RU
RWANDA RW
Country or Region Country or Region Code
Countries and Regions Supported by PayPal
B
268 August 2012 Name-Value Pair API Developer Guide
SAINT HELENA SH
SAINT KITTS AND NEVIS KN
SAINT LUCIA LC
SAINT PIERRE AND MIQUELON PM
SAINT VINCENT AND THE GRENADINES VC
SAMOA WS
SAN MARINO SM
SAO TOME AND PRINCIPE * ST *
SAUDI ARABIA SA
SENEGAL SN
SERBIA RS
SEYCHELLES SC
SINGAPORE SG
SLOVAKIA SK
SLOVENIA SI
SOLOMON ISLANDS SB
SOUTH AFRICA ZA
SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS GS
SPAIN ES
SURINAME SR
SVALBARD AND JAN MAYEN SJ
SWAZILAND SZ
SWEDEN SE
SWITZERLAND CH
TAIWAN, PROVINCE OF CHINA TW
TANZANIA, UNITED REPUBLIC OF TZ
THAILAND TH
TIMOR-LESTE TL
TOGO TG
TOKELAU TK
TONGA TO
Country or Region Country or Region Code
Name-Value Pair API Developer Guide August 2012 269
Countries and Regions Supported by PayPal B
TRINIDAD AND TOBAGO TT
TUNISIA TN
TURKEY TR
TURKMENISTAN TM
TURKS AND CAICOS ISLANDS TC
TUVALU TV
UGANDA UG
UKRAINE UA
UNITED ARAB EMIRATES AE
UNITED KINGDOM GB
UNITED STATES US
UNITED STATES MINOR OUTLYING ISLANDS UM
URUGUAY UY
UZBEKISTAN UZ
VANUATU VU
VENEZUELA VE
VIET NAM VN
VIRGIN ISLANDS, BRITISH VG
VIRGIN ISLANDS, U.S. VI
WALLIS AND FUTUNA WF
WESTERN SAHARA EH
ZAMBIA ZM
Country or Region Country or Region Code
Countries and Regions Supported by PayPal
B
270 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 271
CState and Province Codes
Canadian Province or U.S. State Abbreviation
Alberta AB
British Columbia BC
Manitoba MB
New Brunswick NB
Newfoundland and Labrador NL
Northwest Territories NT
Nova Scotia NS
Nunavut NU
Ontario ON
Prince Edward Island PE
Quebec QC
Saskatchewan SK
Yukon YT
Alabama AL
Alaska AK
American Samoa AS
Arizona AZ
Arkansas AR
California CA
Colorado CO
Connecticut CT
Delaware DE
District of Columbia DC
Federated States of Micronesia FM
Florida FL
Georgia GA
State and Province Codes
C
272 August 2012 Name-Value Pair API Developer Guide
Guam GU
Hawaii HI
Idaho ID
Illinois IL
Indiana IN
Iowa IA
Kansas KS
Kentucky KY
Louisiana LA
Maine ME
Marshall Islands MH
Maryland MD
Massachusetts MA
Michigan MI
Minnesota MN
Mississippi MS
Missouri MO
Montana MT
Nebraska NE
Nevada NV
New Hampshire NH
New Jersey NJ
New Mexico NM
New York NY
North Carolina NC
North Dakota ND
Northern Mariana Islands MP
Ohio OH
Oklahoma OK
Oregon OR
Palau PW
Canadian Province or U.S. State Abbreviation
Name-Value Pair API Developer Guide August 2012 273
State and Province Codes C
Pennsylvania PA
Puerto Rico PR
Rhode Island RI
South Carolina SC
South Dakota SD
Tennessee TN
Texas TX
Utah UT
Vermont VT
Virgin Islands VI
Virginia VA
Washington WA
West Virginia WV
Wisconsin WI
Wyoming WY
Armed Forces Americas AA
Armed Forces AE
Armed Forces Pacific AP
Canadian Province or U.S. State Abbreviation
State and Province Codes
C
274 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 275
DCurrency Codes
PayPal uses 3-character ISO-4217 codes for specifying currencies in fields and variables.
Currencies and Currency Codes Supported by PayPal
Currency Currency Code
Australian Dollar AUD
Brazilian Real
NOTE:This currency is supported as a payment
currency and a currency balance for in-country
PayPal accounts only.
BRL
Canadian Dollar CAD
Czech Koruna CZK
Danish Krone DKK
Euro EUR
Hong Kong Dollar HKD
Hungarian Forint HUF
Israeli New Sheqel ILS
Japanese Yen JPY
Malaysian Ringgit
NOTE:This currency is supported as a payment
currency and a currency balance for in-country
PayPal accounts only.
MYR
Mexican Peso MXN
Norwegian Krone NOK
New Zealand Dollar NZD
Philippine Peso PHP
Polish Zloty PLN
Pound Sterling GBP
Singapore Dollar SGD
Swedish Krona SEK
Swiss Franc CHF
Taiwan New Dollar TWD
Currency Codes
D
276 August 2012 Name-Value Pair API Developer Guide
Currencies and Currency Codes Supported by Express Checkout and Direct Payment
Thai Baht THB
Turkish Lira
NOTE:This currency is supported as a payment
currency and a currency balance for in-country
PayPal accounts only.
TRY
U.S. Dollar USD
Express
Checkout
Currency
Cur-
rency
Code
Direct Payment
Currency for Specified
Card in United States
Direct Payment
Currency for Specified
Card in United Kingdom
Direct Payment
Currency for Specified
Card in Canada
Australian
Dollar
AUD Visa, MasterCard Visa, MasterCard Visa, MasterCard
Canadian
Dollar
CAD Visa, MasterCard Visa, MasterCard Visa, MasterCard
Czech Koruna CZK Visa, MasterCard Visa, MasterCard
Danish Krone DKK Visa, MasterCard Visa, MasterCard
Euro EUR Visa, MasterCard Visa, MasterCard Visa, MasterCard
Hong Kong
Dollar
HKD Visa, MasterCard Visa, MasterCard
Hungarian
Forint
HUF Visa, MasterCard Visa, MasterCard
Japanese Yen JPY Visa, MasterCard Visa, MasterCard Visa, MasterCard
Norwegian
Krone
NOK Visa, MasterCard Visa, MasterCard
New Zealand
Dollar
NZD Visa, MasterCard Visa, MasterCard
Polish Zloty PLN Visa, MasterCard Visa, MasterCard
Pound Sterling GBP Visa, MasterCard Visa, MasterCard, Maestro Visa, MasterCard
Singapore
Dollar
SGD Visa, MasterCard Visa, MasterCard
Swedish Krona SEK Visa, MasterCard Visa, MasterCard
Swiss Franc CHF Visa, MasterCard Visa, MasterCard
U.S. Dollar USD Visa, MasterCard,
Discover, American
Express
Visa, MasterCard Visa, MasterCard
Currency Currency Code
Name-Value Pair API Developer Guide August 2012 277
EAVS and CVV2 Response Codes
AVS Response Codes
Related information:
DoDirectPayment Response Fields
AVS Response Codes for Visa, MasterCard, Discover, and American
Express
AVS Code Meaning Matched Details
AAddress Address only (no ZIP code)
BInternational “A” Address only (no ZIP code)
CInternational “N” None
NOTE:The transaction is declined.
DInternational “X” Address and Postal Code
ENot allowed for MOTO
(Internet/Phone) transactions
Not applicable
NOTE:The transaction is declined.
FUK-specific “X” Address and Postal Code
GGlobal Unavailable Not applicable
IInternational Unavailable Not applicable
MAddress Address and Postal Code
NNo None
NOTE:The transaction is declined.
PPostal (International “Z”) Postal Code only (no Address)
RRetry Not applicable
SService not Supported Not applicable
UUnavailable Not applicable
WWhole ZIP Nine-digit ZIP code (no Address)
AVS and CVV2 Response Codes
AVS Response Codes
E
278 August 2012 Name-Value Pair API Developer Guide
Related information:
DoDirectPayment Response Fields
AVS Response Codes for Maestro
Related information:
DoDirectPayment Response Fields
XExact match Address and nine-digit ZIP code
YYes Address and five-digit ZIP
ZZIP Five-digit ZIP code (no Address)
All others Error Not applicable
AVS Code Meaning Matched Details
0 All the address information matched. All information matched
1 None of the address information
matched.
None
NOTE:The transaction is declined.
2 Part of the address information
matched.
Partial
3 The merchant did not provide AVS
information. Not processed.
Not applicable
4 Address not checked, or acquirer had
no response. Service not available.
Not applicable
Null No AVS response was obtained.
Default value of field.
Not applicable
AVS Code Meaning Matched Details
Name-Value Pair API Developer Guide August 2012 279
AVS and CVV2 Response Codes
CVV2 Response Codes E
CVV2 Response Codes
CVV2 Response Codes for Visa, MasterCard, Discover, and American
Express
CVV2 Response Codes for Maestro
CVV2 Code Meaning Matched Details
EError - Unrecognized or Unknown
response
Not applicable
IInvalid or Null Not applicable
MMatch CVV2CSC
NNo match None
PNot processed Not applicable
SService not supported Not applicable
UService not available Not applicable
XNo response Not applicable
CVV2 Code Meaning Matched Details
0 Matched CVV2
1 No match None
2 The merchant has not implemented
CVV2 code handling
Not applicable
3 Merchant has indicated that CVV2 is
not present on card
Not applicable
4 Service not available Not applicable
All others Error Not applicable
AVS and CVV2 Response Codes
CVV2 Response Codes
E
280 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 281
About Previous Versions of the
API
Previous versions of the API can still be used; however, PayPal recommends using the latest
version whenever possible. Unless specifically specified, API operations default to the latest
version.
What’s New in Version 92.0
Updated for 92.0. Added new MsgSubID field for the following APIs for both requests and
responsees: RefundTransaction; DoReferenceTransaction; DoAuthorization; and DoCapture.
What’s New in Version 89.0
Updated for 89.0. Added new field to SetExpressCheckout and DoReferenceTransaction
Request APIs. Added new error to DoReferenceTransaction Request API.
What’s New in Version 88.0
Maintenance release, updated for 88.0.
What’s New in Version 85.0
No new features added; solely a maintenance release.
What’s New in Version 84.0
What’s New in Version 84.0
282 August 2012 Name-Value Pair API Developer Guide
New Field in RefundTransaction Response
New RefundInfoType in RefundTransaction Response
New Field in DoReferenceTransactionResponseDetailsType
New Field in DoDirectPaymentResponse
Field Description
REFUNDINFO Contains refund payment status information.
This field is available since version 84.0.
Field Description
REFUNDSTATUS Status of the refund. It is one of the following values:
-instant
-delayed
This field is available since version 84.0.
PENDINGREASON Reason that the payment is delayed. It is one of the following values:
-none – The refund is instant.
-echeck – The refund is delayed.
This field is available since version 84.0.
Field Description
PAYMENTADVICECODE Response code from the processor when a recurring transaction is declined.
For details on the meanings of the codes, see
https://merchant.paypal.com/us/cgi-bin/?&cmd=_render-
content&content_ID=merchant/cc_compliance_error_codes
This field is available since version 84.0.
Field Description
PAYMENTADVICECODE Response code from the processor when a recurring transaction is declined.
For details on the meanings of the codes, see
https://merchant.paypal.com/us/cgi-bin/?&cmd=_render-
content&content_ID=merchant/cc_compliance_error_codes
This field is available since version 84.0.
Name-Value Pair API Developer Guide August 2012 283
What’s New in Version 82.0
What’s New in Version 82.0
New Field in DoCapture Request
New MerchantStoreDetailsType in DoCapture Request
New Fields in RefundTransaction Request
Field Description
MERCHANTSTOREDETAILS (Optional) Information about the merchant store.
This field is available since version 82.0.
Field Description
STOREID ID of the merchant store. This field is required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters
This field is available since version 84.0.
TERMINALID (Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
Field Description
MERCHANTSTOREDETAILS (Optional) Information about the merchant store.
This field is available since version 82.0.
RETRYUNTIL (Optional) Maximum time until you must retry the refund.
NOTE:This field does not apply to point-of-sale transactions.
This field is available since version 82.0.
What’s New in Version 82.0
284 August 2012 Name-Value Pair API Developer Guide
New MerchantStoreDetailsType in RefundTransaction Request
REFUNDSOURCE (Optional)Type of PayPal funding source (balance or eCheck) that can be used for
auto refund. It is one of the following values:
-any – The merchant does not have a preference. Use any available funding
source.
-default – Use the merchant’s preferred funding source, as configured in the
merchant’s profile.
-instant – Use the merchant’s balance as the funding source.
-eCheck – The merchant prefers using the eCheck funding source. If the
merchant’s PayPal balance can cover the refund amount, use the PayPal
balance.
NOTE:This field does not apply to point-of-sale transactions.
This field is available since version 82.0.
REFUNDTYPE Type of refund you are making. It is one of the following values:
-Full – Full refund (default).
-Partial – Partial refund.
-ExternalDispute – External dispute. (Value available since version 82.0)
-Other – Other type of refund. (Value available since version 82.0)
Field Description
STOREID ID of the merchant store. This field is required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters
This field is available since version 84.0.
TERMINALID (Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
Field Description
Name-Value Pair API Developer Guide August 2012 285
What’s New in Version 80.0
What’s New in Version 80.0
New Fields in PaymentDetailsType in DoReferenceTransaction Request
What’s New in Version 74.0
New Behavior of DoExpressCheckoutPayment
By default, the DoExpressCheckoutPayment API operation is idempotent for all API
callers. You can call DoExpressCheckoutPayment up to a maximum of 10 times, and it
returns the same result. The exceptions are when DoExpressCheckoutPayment generates
an error or the token expires.
This functionality only works with version 74.0 or greater. There is no change to
DoExpressCheckoutPayment functionality if you are not updating to the latest version of
the API.
If you update to version 74.0 or higher but want to opt out of this functionality, contact PayPal.
New DoExpressCheckoutPayment Error Code
Field Description
RECURRING (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.
Error
Code Short Message Long Message Correcting This Error...
13751 Could not retrieve the
original successful
response.
Transaction completed
successfully, but could not
retrieve the original successful
response.
What’s New in Version 72.0
286 August 2012 Name-Value Pair API Developer Guide
What’s New in Version 72.0
New TaxIdDetailsType Structure in SetExpressCheckout Request
TaxIdDetailsType Fields
New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response
TaxIdDetailsType Fields
Field Description
TAXIDTYPE New field
The buyer’s tax ID type. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for
businesses.
TAXID New field
The buyer’s tax ID. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID is 11 single-byte character for individuals and 14
single-byte characters for businesses.
Field Description
TAXIDTYPE New field
The buyer’s tax ID type. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for
businesses.
TAXID New field
The buyer’s tax ID. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID is 11 single-byte character for individuals and 14
single-byte characters for businesses.
Name-Value Pair API Developer Guide August 2012 287
What’s New in Version 69
What’s New in Version 69
New PaymentDetailsItemType Structure in
CreateRecurringPaymentsProfile Request
PaymentDetailsItemType Fields
Field Description
L_PAYMENTREQUEST_n_IT
EMCATEGORYm
New field
Indicates whether the item is digital or physical goods. For digital goods, this field
is required and you must set it to Digital to get the best rates. It is one of the
following values:
-Digital
-Physical
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMCATEGORY0,
L_PAYMENTREQUEST_n_ITEMCATEGORY1).
L_PAYMENTREQUEST_n_NA
MEm
New field
Item name.This field is required when you pass a value for ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).
Character length and limitations: 127 single-byte characters
L_PAYMENTREQUEST_n_DE
SCm
New field
(Optional) Item description.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_DESC0, L_PAYMENTREQUEST_n_DESC1).
Character length and limitations: 127 single-byte characters
L_PAYMENTREQUEST_n_AM
Tm
New field
Cost of item. This field is required when you pass a value for ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).
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.
L_PAYMENTREQUEST_n_NU
MBERm
New field
(Optional) Item number.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NUMBER0, L_PAYMENTREQUEST_n_NUMBER1).
What’s New in Version 69
288 August 2012 Name-Value Pair API Developer Guide
Changes to PaymentDetailsItemType in DoReferenceTransaction Request
PaymentDetailsItemType Fields
L_PAYMENTREQUEST_n_QT
Ym
New field
Item quantity. This field is required when you pass a value for ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).
Character length and limitations: Any positive integer
L_PAYMENTREQUEST_n_TA
XAMTm
New field
(Optional) Item sales tax.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_TAXAMT0, L_PAYMENTREQUEST_n_TAXAMT1).
Character length and limitations: Must not exceed $10,000 USD in any currency.
No currency symbol. Regardless of currency, decimal separator must be a period
(.), and the optional thousands separator must be a comma (,). Equivalent to nine
characters maximum for USD.
Field Description
L_ITEMCATEGORYnNew field
Indicates whether the item is digital or physical goods. For digital goods, this
field is required and you must set it to Digital to get the best rates. It is one
of the following values:
-Digital
-Physical
These parameters must be ordered sequentially beginning with 0 (for example
L_ITEMCATEGORY0, L_ITEMCATEGORY1).
L_NAMEnItem name. This field is required when you pass a value for ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_NAME0, L_NAME1).
Character length and limitations: 127 single-byte characters
L_AMTnCost of item. This field is required when you pass a value for ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_AMT0, L_AMT1).
NOTE:If you specify a value for L_AMTn, you must specify a value for
ITEMAMT.
Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator must
be a period (.), and the optional thousands separator must be a comma (,).
Equivalent to nine characters maximum for USD.
Field Description
Name-Value Pair API Developer Guide August 2012 289
What’s New in Version 66
What’s New in Version 66
Changes to PaymentDetailsType in SetExpressCheckout and
DoExpressCheckoutPayment Requests
PaymentDetailsType Fields
Changes to PaymentDetailsItemTypein SetExpressCheckout and
DoExpressCheckoutPayment Requests
PaymentDetailsItemType Fields
L_QTYnItem quantity. This field is required when you pass a value for
ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_QTY0, L_QTY1).
Character length and limitations: Any positive integer
Field Description
PAYMENTREQUEST_n_ITEMAMT
ITEMAMT (deprecated)
Sum of cost of all items in this order. For digital goods, this field is required.
NOTE:PAYMENTREQUEST_n_ITEMAMT is required if you specify
L_PAYMENTREQUEST_n_AMTm.
ITEMAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ITEMAMT instead.
PAYMENTREQUEST_n_PAYMENT
ACTION
PAYMENTACTION (deprecated)
How you want to obtain payment. When implementing digital goods, this field
is required and you must set it to Sale.
PAYMENTACTION is deprecated since version 63.0. Use
PAYMENTREQUEST_0_PAYMENTACTION instead.
Field Description
L_PAYMENTREQUEST_n_ITEMC
ATEGORYm
New field
Indicates whether the item is digital or physical goods. This field is available
since version 65.1. For digital goods this field is required and you must set it to
Digital. It is one of the following values:
-Digital
-Physical
Field Description
What’s New in Version 66
290 August 2012 Name-Value Pair API Developer Guide
L_PAYMENTREQUEST_n_NAME
m
L_NAMEn (deprecated)
Item name. For digital goods, this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).
Character length and limitations: 127 single-byte characters
L_NAMEn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_NAMEm instead.
L_PAYMENTREQUEST_n_DESC
m
L_DESCn (deprecated)
Item description. For digital goods, this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_DESC0, L_PAYMENTREQUEST_n_DESC1).
Character length and limitations: 127 single-byte characters
L_DESCn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_DESCm instead.
L_PAYMENTREQUEST_n_AMTm
L_AMTn (deprecated)
Cost of item. For digital goods, this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).
NOTE:If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must
specify a value for PAYMENTREQUEST_n_ITEMAMT.
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.
L_AMTn is deprecated since version 63.0. Use L_PAYMENTREQUEST_0_AMTm
instead.
L_PAYMENTREQUEST_n_QTYm
L_QTYn (deprecated)
Item quantity. For digital goods, this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).
Character length and limitations: Any positive integer
L_QTYn is deprecated since version 63.0. Use L_PAYMENTREQUEST_0_QTYm
instead.
Field Description
Name-Value Pair API Developer Guide August 2012 291
What’s New in Version 66
Changes to PaymentDetailsItemType in GetExpressCheckoutDetails
Response
Field Description
L_PAYMENTREQUEST_n_ITEMC
ATEGORYm
New field
Inicates whethe item is digital or physical goods. For digital goods this field is
required and you must set it to Digital. It is one of the following values:
-Digital
-Physical
This field is available since version 65.1.
What’s New in Version 66
292 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 293
Revision History
Date Description
10 August 2012 Maintenance release. Added CVV2 response codes E and I for Visa,
Mastercard, Discover and American Express.
7 August 2012 Maintenance release. New 10486 error code added for redirects when the
process declines the transaction: The transaction couldn’t be completed. Please
redirect your customer to PayPal.
10 July 2012 Updated for 92.0. Added new MsgSubID field for the following APIs for both
requests and responsees: RefundTransaction; DoReferenceTransaction;
DoAuthorization; and DoCapture.
12 June 2012 Maintenance release
22 May 2012 Maintenance release
2 May 2012 Updated for 89.0. Added new field to SetExpressCheckout and
DoReferenceTransaction Request APIs. Added new error to
DoReferenceTransaction Request API.
3 April 2012 Updated references to Website Payments Standard and Website Payments Pro to
PayPal Payments Standard and PayPal Payments Pro, respectively.
14 February 2012 Maintenance release
24 January 2012 Maintenance release, updated for 85.0.
1November 2011 Updated for 84.0. Added new field and a new type to RefundTransaction API
request. Added new field to DoDirectPayment API and
DoReferenceTransaction API responses. Edits to improve accuracy.
1 September 2011 General edits to improve consistency.
5 April 2011 Updated for 71.0. Added new fields to the DoExpressCheckout API response to
return information about funds that are being held and the seller’s encrypted
account number.
8 March 2011 Updated for 69.0. Added more digital goods support to the
CreateRecurringPaymentsProfile and DoReferenceTransaction APIs to enable
the merchant to obtain the best rates for digital goods.
26 January 2011 Updated for 66.0. Describes changes to the ExpressCheckout API for
implementing Digital Goods.
15 September 2010 Updated for 64.4, including addition of ProtectionEligibilityType field.
294 August 2012 Name-Value Pair API Developer Guide
11 May 2010 Updated for 63.0. Added new NVP API fields to use in version 63.0 Express
Checkout integrations. Deprecated old fields. Updated billing agreement API
with functionality to obtain the latest billing address and to skip billing
agreement creation. Added ReverseTransaction API.
10 March 2010 Updated information for 62.0: Describes Express Checkout fields recommended
to be used in applications that enable implementing parallel payments for a
marketplace.
21 January 2010 Updated information for 61.0: Added Express Checkout fields enabling you to
provide gift and insurance options to the PayPal checkout pages.
7 October 2009 Updated information for 60.0: updated currency table with new currencies, and
added Express Checkout API fields for Immediatee Payment and eBay.
16 June 2009 Updated information for 58.0: added GetPalDetails API and fields for payment
review.
22 May 2009 Minor update to version 57.0; added CreateBillingAgreement to
Enterprise edition.
08 April 2009 Updated information for 57.0: Express Checkout Callback API and error codes.
26 Nov. 2008 Updated information for 55.0.
23 Sept. 2008 Added information about using billing agreements with SetExpressCheckout.
3 Sept. 2008 Added information about payment review to GetTransactionDetails.
June 2008 Rearranged material, added error codes, and moved some material to the
Express Checkout Integration Guide.
April 2008 Added Fraud Management Filters information. Changed recurring payments
information.
February 2008 Added that ther VERSION parameter must be 50.0 in the API call to use
recurring payments.
January 2008 -Added billing agreement fields to SetExpressCheckout for recurring
payments
-Updated CreateRecurringPaymentsProfile for new recurring payments
features.
-Added new recurring payments APIs
-Added DoNonReferencedCredit API
September 2007 -Update eBay auctions for Express Checkout section
-Added fields for the giropay payment method to Express Checkout APIs
-Added Direct Payment error 10571.
August 2007 Added recurring payments concepts, modified SetExpressCheckout,
DoExpressCheckoutPayment, DoReferenceTransaction, and added
additional DoReferenceTransaction error codes.
Date Description
Name-Value Pair API Developer Guide August 2012 295
April 2007 Added Recurring Payments APIs: SetCustomerBillingAgreement,
GetBillingAgreementCustomerDetails, and
CreateRecurringPaymentsProfile.
February 2007 Bug fixes including updating Line Item Details for Direct Payment and Express
Checkout APIs, changing some parameters to optional in DoDirectPayment,
adding SHIPTOCOUNTRYCODE, and adding Switch/Solo codes for AVS and
CVV2.
December 2006 Updates for bug fixes.
October 2006 First public release.
11 May 2010 Added new NVP API fields to use in version 63.0 Express Checkout
integrations. Deprecated old fields. Updated billing agreement API with
functionality to obtain the latest billing address and to skip billing agreement
creation. Added ReverseTransaction API.
Date Description
296 August 2012 Name-Value Pair API Developer Guide
Name-Value Pair API Developer Guide August 2012 297
Index
Numerics
3-D Secure request fields 47
3D Secure response fields 50
A
ACCT request field 42, 52, 142, 160, 177, 190
ACCT response field 152
ACTION request field 133, 154
Activation Details request fields 141
ADDITIONALBILLINGCYCLES request field 156
Address request fields 43, 53, 143, 160, 178
Address response fields 124, 153
Address Verify request fields 25
Address Verify response fields 26
ADDRESSOWNER response field 124, 153
ADDRESSSTATUS response field 82, 124, 148, 153,
167
AddressVerify API operation 25
AddressVerify request message 25
AddressVerify response message 26
ADDROVERRIDE request field 61
AGGREGATEAMOUNT response field 147
AGGREGATEOPTIONALAMOUNT response
field 147
ALLOWEDPAYMENTMETHOD request field 70, 98
ALLOWEDPAYMENTMETHOD respo nse field 86
ALLOWNOTE request field 61
ALLOWPUSHFUNDING request field 76
American Express AVS response codes 277
American Express CVV2 response codes 279
AMT request field 27, 32, 36, 43, 51, 59, 67, 94, 139,
155, 156, 158, 173, 185
AMT response field 33, 48, 83, 109, 126, 131, 150, 180
AUCTI ONITEMNUMBER reque st field 190
Auction Information response fields 131
AUD 275, 276
Australian Dollar 275, 276
Authorization and Capture API Operation Reference 27
Authorization Type response fields 34, 37
AUTHORIZATIONID request field 27, 36, 39
AUTHORIZATIONID response field 29, 37, 39
AUTHSTATUS3DS request field 47
AUTOBILLAMT request field 138
AUTOBILLOUTAMT request field 157
AUTOBILLOUTAMT response field 147
AVS and CVV2 response codes 277
AVS response codes 277
AVSCODE response field 48, 178
B
BA Update request fields 168
BA Update response fields 168
BANKTXNPENDINGURL request field 64
BAUpdate API operation 168
BAUpdate request message 168
BAUpdate response message 168
Bill Outstanding Amount request fields 155
Bill Outstanding Amount response fields 155
Billing Period Details request fields 139, 158
Billing Period Details response fields 148
BILLINGAGREEMENTID response field 106, 162,
178
BILLINGAGREEMENTSTATUS request field 168
BILLINGAGREEMENTSTATUS response fie ld 169
BILLINGFREQUENCY request field 139
BILLINGFREQUENCY response field 149
BILLINGPERIOD request field 139
BILLINGPERIOD response field 148
BILLINGTYPE request field 77, 165
BillOutstanding API operation 155
BillOutstandingAmount request message 155
BillOutstandingAmount response message 155
BRANDNAME request field 64
Brazilian Real 275
BRL 275
BUSINESS request field 143
BUSINESS response field 81
BUTTONSOURCE request field 45, 94, 174
Buyer Details request fields 75
BUYEREMAILOPTINENABLE request field 65
Index
298 August 2012 Name-Value Pair API Developer Guide
BUYERID request field 75
BUYERID response field 131
BUYERMARKETINGEMAIL request field 93
BUYERMARKETINGEMAIL response field 80, 122
BUYERREGISTRATIONDATE request field 76
BUYERUSERNAME request field 76
C
CAD 275, 276
Callback API operation 55
CALLBACK request field 60
Callback request fields 55
Callback request message 55
Callback response fields 58
Callback response message 58
CALLBACKTIMEOUT request field 60
CALLBACKVERSION request field 61
Canadian Dollar 275, 276
CANCELURL request field 60, 162
CAVV request field 48
CHANNELTYPE request field 64
character encoding 16
CHECKOUTSTATUS response field 80
CHF 275, 276
CITY request field 43, 53, 144, 160, 178
CLOSINGDATE response field 131
COMPLETETYPE request field 27
CONFIRMATIONCODE response field 26
COUNTRYCODE 123, 166, 169
COUNTRYCODE request field 43, 54, 143, 144, 161,
178
COUNTRYCODE response field 26, 81
CouponAmount response field 130
CouponAmountCurrency 130
CouponID 130
Create Billing Agreement request fields 161
Create Billing Agreement response fields 162
Create Recurring Payments Profile request fields 137
Create Recurring Payments Profile response fields 145
CreateBillingAgreement API operation 161
CreateBillingAgreement request message 161
CreateBillingAgreement response message 162
CreateRecurringPaymentsProfile API operation 137
CreateRecurringPaymentsProfile request message 137
CreateRecurringPaymentsProfile response
message 145
Credit Card Details request fields 42, 52, 142, 159, 177
Credit Card Details response fields 152
CREDITCARDTYPE request field 42, 52, 142, 159,
177
CREDITCARDTYPE response field 152
currency codes 275, 276
CURRENCYCODE request field 27, 33, 36, 43, 52, 55,
58, 67, 94, 135, 140, 159, 173, 185, 188, 190
CURRENCYCODE response field 54, 83, 109, 126,
151, 180
CUSTOM request field 45, 69, 97, 174
CUSTOM response field 79, 85, 129
CUSTOMERSERVICENUMBER request field 64
CVV2 request field 42, 52, 142, 160, 177
CVV2 response codes 279
CVV2MATCH response field 48, 178
Czech Koruna 275, 276
CZK 275, 276
D
Danish Krone 275, 276
DESC request field 45, 69, 96, 138, 156, 174
DESC response field 85, 147
Discover AVS response codes 277
Discover CVV2 response codes 279
DKK 275, 276
Do Authorization request fields 32
Do Authorization response fields 33
Do Capture request fields 27
Do Capture response fields 29
Do Direct Payment request field 41
Do Direct Payment response fields 48
Do ExpressCheckout Payment request fields 92
Do ExpressCheckout Payment response fields 105
Do NonReferenced Credit request fields 51
Do NonReferenced Credit response fields 54
Do Reauthorization request fields 36
Do Reauthorization response fields 37
Do Reference Transaction request fields 171
Do Reference Transaction response fields 178
Do Void request fields 39
Do Void response fields 39
DoAuthorization API operation 32
DoAuthorization request message 32
DoAuthorization response message 33
DoCapture API operation 27
Name-Value Pair API Developer Guide August 2012 299
Index
DoCapture request message 27
DoCapture response message 29
DoDirectPayment API operation 41
DoDirectPayment request message 41
DoDirectPayment response message 48
DoExpressCheckoutPayment API operation 92
DoExpressCheckoutPayment request message 92
DoExpressCheckoutPayment response message 105
DoNonReferencedCredit API operation 51
DoNonReferencedCredit request message 51
DoNonReferencedCredit response message 54
DoReauthorization API operation 36
DoReauthorization request message 36
DoReauthorization response message 37
DoReferenceTransaction API operation 171
DoReferenceTransaction request message 171
DoReferenceTransaction response message 178
DoVoid API operation 39
DoVoid request message 39
DoVoid response message 39
E
Ebay Item Payment Details Item request fields 46, 75,
103, 176
Ebay Item Payment Details Item response fields 89
EBAYITEMAUCTIONTXNID response field 113
EBAYITEMAUCTIONTXNIDn response field 90
EBAYITEMCARTIDn response field 90
EBAYITEMNUMBERn response field 89
EBAYITEMORDERIDn response field 90
EbayItemTxnId response field 130
ECI3DS request field 48
ECISUBMITTED3DS response field 50
EMAIL request field 25, 42, 53, 63, 143, 160, 177, 189
EMAIL response field 80, 123, 152, 166, 169
EMAILSUBJECT request field 135
ENDDATE request field 189
error codes 193
error responses 23
EUR 275, 276
Euro 275, 276
EXCHANGERATE response field 110, 126, 181
EXPDATE request field 42, 52, 142, 160, 177
EXPDATE response field 152
ExpressCheckout API Operatons 55
F
FAILEDINITAMTACTION request field 141
FAILEDPAYMENTCOUNT response field 151
FEEAMT response field 109, 126, 180
FEEREFUNDAMT response field 187
FINALPAYMENTDUEDATE response field 147
FIRSTNAME request field 42, 53, 143, 160, 177, 191
FIRSTNAME respo n se field 152
FIRSTNAME response field 81, 124, 167, 169
Forint 275, 276
Funding Source Details request fields 76
G
GBP 275, 276
Get Balance request fields 117
Get Balance response fields 117
Get Billing Agreement Customer Details request
fields 166
Get ExpressCheckout Details request fields 78
Get ExpressCheckout Details response fields 79
Get Pal Details request fields 119
Get Pal Details response fields 119
Get Recurring Payments Profile Details request
fields 146
Get Recurring Payments Profile Details response
fields 146
Get Transaction Details request fields 121
Get Transaction Details response fields 121
GetBalance API operation 117
GetBalance request message 117
GetBalance response message 117
GetBillingAgreementCustomerDetails API
operation 166
GetBillingAgreementCustomerDetails request
message 166
GetBillingAgreementCustomerDetails response
message 166
GetExpressCheckoutDetails API operation 78
GetExpressCheckoutDetails request message 78
GetExpressCheckoutDetails response message 79
GetPalDetails API operation 119
GetPalDetails request message 119
GetPalDetails response message 119
GetRecurringPaymentsProfileDetails API
operation 146
Index
300 August 2012 Name-Value Pair API Developer Guide
GetRecurringPaymentsProfileDetails request
message 146
GetRecurringPaymentsProfileDetails response
message 146
GetTransactionDetails API operation 121
GetTransactionDetails request message 121
GetTransactionDetails response message 121
GIFTMESSAGE request field 93
GIFTMESSAGE response field 80, 122
GIFTMESSAGEENABLE request field 64
GIFTRECEIPTENABLE request field 64, 93
GIFTRECEIPTENABLE response field 80, 122
GIFTWRAPAMOUNT request field 65, 93
GIFTWRAPAMOUNT response field 80, 122
GIFTWRAPENABLE request field 64
GIFTWRAPNAME request field 64, 93
GIFTWRAPNAME response field 80, 122
GIROPAYCANCELURL request field 64
GIROPAYSUCCESSURL request field 64
GROSSREFUNDAMT response field 187
H
HANDLINGAMT requ e st f i eld 174
HANDLINGAMT request field 44, 69, 96
HANDLINGAMT response field 85
HDRBACKCOLOR request field 63, 164
HDRBORDERCOLOR request field 63, 164
HDRIMG request field 63, 164
HKD 275
Hong Kong Dollar 275
HUF 275, 276
Hungarian Forint 275, 276
I
ILS 275
INITAMT request field 141
InstrumentDetails response field 114
INSURANCEAMT request field 44, 68, 95
INSURANCEAMT response field 84
INSURANCEOPTIONOFFERED request field 68, 96
INSURANCEOPTIONOFFERED response field 84
INSURANCEOPTIONSELECTED request field 104
INSURANCEOPTIONSELECTED response field 90,
115, 122
INVNUM request field 28, 45, 70, 174, 185, 189
INVNUM response field 79, 86, 129
IPADDRESS request field 41, 171
Israeli Sheqel 275
ISSUENUMBER request field 42, 52, 142, 160, 177
ISSUENUMBER response field 152
ITE MAMT request field 44
ITEMAMT request field 67, 95, 173, 289
ITEMAMT response field 83
J
Japanese Yen 275, 276
JPY 275, 276
K
Koruna 275, 276
Krona 275, 276
Krone 275, 276
L
L_AMT request field 46, 175, 288
L_AMTn request field 57, 72, 100, 290
L_AMTn response field 87, 117, 130, 192
L_BILLINGAGREEMENTCUSTOMn request
field 77, 165, 168
L_BILLINGAGREEMENTCUSTOMn response
field 169
L_BILLINGAGREEMENTDESCRIPTIONn request
field 77, 165, 168
L_BILLINGAGREEMENTDESCRIPTIONn response
field 168
L_BILLINGAGREEMENTMAXn response field 169
L_BILLINGTYPEn request field 77, 164
L_BILLINGTYPEn response field 168
L_COUPONAMOUNTCurrencyn response field 130
L_COUPONAMOUNTn response field 130
L_COUPONIDn response field 130
L_CURRENCYCODEn response field 117, 192
L_DESCn request field 46, 57, 72, 100, 175, 290
L_DESCn response field 87, 130
L_EBAYITEMAUCTIONTXNIDn request field 46,
75, 103, 176
L_EBAYITEMCARTIDn request field 75, 104
L_EBAYITEMNUMBERn request field 46, 75, 103,
176
Name-Value Pair API Developer Guide August 2012 301
Index
L_EBAYITEMORDERIDn request field 47, 75, 103,
176
L_EBAYITEMTXNID response field 130
L_EMAILn response field 192
L_FEEAMTn response field 192
L_FMFfilterIDn response field 49, 106, 114, 179
L_FMFfilterNAM E n response field 114
L_FMFfilterNAMEn response field 49, 106, 179
L_INSURANCEAMOUNT response field 59
L_ITEMCATEGORYn 175, 288
L_ITEMHEIGHTUNITn request field 57, 74, 102
L_ITEMHEIGHTUNITn response field 89
L_ITEMHEIGHTVALUEn request field 57, 74, 102
L_ITEMHEIGHTVALUEn response field 89
L_ITEMLENGHTUNITn request field 73, 102
L_ITEMLENGTHUNITn request field 57
L_ITEMLENGTHUNITn response field 88
L_ITEMLENGTHVALUEn request field 57, 73, 102
L_ITEMLENGTHVALUEn response field 88
L_ITEMURLn request field 74, 102
L_ITEMWEIGHTUNITn request field 57, 73, 101
L_ITEMWEIGHTUNITn response field 88
L_ITEMWEIGHTVALUEn request field 57, 73, 101
L_ITEMWEIGHTVALUEn response field 88
L_ITEMWIDTHUNITn request field 57, 73, 102
L_ITEMWIDTHUNITn response field 89
L_ITEMWIDTHVALUEn request field 57, 73, 102
L_ITEMWIDTHVALUEn response field 89
L_LOYALTYCARDDISCOUNTAMOUNTn response
field 130
L_LOYALTYCARDDISCOUNTCURRENCYn
response field 130
L_NAMEn request field 46, 56, 71, 100, 175, 288, 290
L_NAMEn response field 87, 192
L_NETAMTn response field 192
L_NUMBER request field 46, 176
L_NUMBERn request field 56, 72, 101
L_NUMBERn response field 88, 130
L_OPTIONSNAMEn response field 131
L_OPTIONSVALUEn response field 131
L_PAYMENTINFO_n_FMFfilterIDm response
field 114
L_PAYMENTINFO_n_FMFfilterNAMEm response
field 114
L_PAYMENTRE
QUEST_n_ITEMWEIGHTVALUEm response
field 88
L_PAYMENTREQUESST_n_EBAYITEMAUCTIONT
XNIDm request field 75, 103
L_PAYMENTREQUEST_n_AMTm request field 72,
100, 145, 287, 290
L_PAYMENTREQUEST_n_AMTm response field 87
L_PAYMENTREQUEST_n_DESCm request field 72,
100, 144, 287, 290
L_PAYMENTREQUEST_n_DESCm response field 87
L_PAYMENTREQUEST_n_EBAYCARTIDm request
field 75, 104
L_PAYMENTREQUEST_n_EBAYITEMAUCTIONT
XNIDm response field 90
L_PAYMENTREQUEST_n_EBAYITEMCARTIDm
response field 90
L_PAYMENTREQUEST_n_EBAYITEMNUMBERm
request field 75, 103
L_PAYMENTREQUEST_n_EBAYITEMNUMBERm
response field 89
L_PAYMENTREQUEST_n_EBAYITEMORDERIDm
request field 75, 103
L_PAYMENTREQUEST_n_EBAYITEMORDERIDm
response field 90
L_PAYMENTREQUEST_n_ITEMCATEGORYm
request field 74, 103, 144, 287
L_PAYMENTREQUEST_n_ITEMCATEGORYm
response field 89
L_PAYMENTREQUEST_n_ITEMHEIGHTUNITm
request field 74, 102
L_PAYMENTREQUEST_n_ITEMHEIGHTUNITm
response field 89
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUEm
request field 74, 102
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUEm
response field 89
L_PAYMENTREQUEST_n_ITEMLENGTHUNITm
request field 73, 102
L_PAYMENTREQUEST_n_ITEMLENGTHUNITm
response field 88
L_PAYMENTREQUEST_n_ITEMLENGTHVALUEm
requ est field 73, 102
L_PAYMENTREQUEST_n_ITEMLENGTHVALUEm
response field 88
L_PAYMENTREQUEST_n_ITEMURLm request
field 74, 102
L_PAYMENTREQUEST_n_ITEMWEIGHTUNITm
request field 73, 101
L_PAYMENTREQUEST_n_ITEMWEIGHTUNITm
response field 88
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUEm
request field 73, 101
Index
302 August 2012 Name-Value Pair API Developer Guide
L_PAYMENTREQUEST_n_ITEMWIDTHUNITm
request field 73, 102
L_PAYMENTREQUEST_n_ITEMWIDTHUNITm
response field 89
L_PAYMENTREQUEST_n_ITEMWIDTHVALUEm
request field 73, 102
L_PAYMENTREQUEST_n_ITEMWIDTHVALUEm
response field 89
L_PAYMENTREQUEST_n_NAMEm request field 71,
100, 144, 287, 290
L_PAYMENTREQUEST_n_NAMEm response
field 87
L_PAYMENTREQUEST_n_NU MBERm response
field 88
L_PAYMENTREQUEST_n_NUMBERm request
field 72, 101, 145, 287
L_PAYMENTREQUEST_n_QTYm request field 72,
101, 145, 288, 290
L_PAYMENTREQUEST_n_QTYm response field 88
L_PAYMENTREQUEST_n_TAXAMTm request
field 73, 88, 101, 145, 288
L_PAYMENTTYPEn request field 77, 165
L_QTY request field 46, 176, 289
L_QTYn request field 57, 72, 101, 290
L_QTYn response field 88, 130
L_SHIPPINGOPTIONAMOUNT response field 58
L_SHIPPINGOPTIONAMOUNTn request field 76
L_SHIPPINGOPTIONAMOUNTn response field 122
L_SHIPPINGOPTIONISDEFAULT response field 58
L_SHIPPINGOPTIONISDEFAULTn request field 76
L_SHIPPINGOPTIONISDEFAULTn response
field 122
L_SHIPPINGOPTIONLABEL response field 58
L_SHIPPINGOPTIONNAME response field 58
L_SHIPPINGOPTIONNAMEn request field 76
L_SHIPPINGOPTIONNAMEn response field 122
L_STATUSn response field 192
L_SURVEYCHOICEn request field 65
L_TAXAMT request fi eld 46
L_TAXAMT request field 176
L_TAXAMT response field 58
L_TAXAMTn request field 73, 88, 101
L_TIMESTAMPn response field 192
L_TIMEZONEn response field 192
L_TRANSACTIONIDn response field 192
L_TYPEn response field 192
LANDINGPAGE request field 64
LASTNAME request field 43, 53, 143, 160, 178, 191
LASTNAME response field 81, 124, 152, 167, 170
LASTPAYMENTAMT response field 151
LASTPAYMENTDATE response field 151
LOCALE response field 120
LOCALECODE request field 56, 62, 163
LoyaltyCardDiscountAmount 130
LoyaltyCardDiscountCurrency 130
M
Maestro AVS response codes 278
Maestro CVV2 response codes 279
Malaysian Ringgit 275
Manage Pending Transaction Status request fields 133
Manage Pending Transaction Status response fields 134
Manage Recurring Payments Profile Status request
fields 154
Manage Recurring Payments Profile Status response
fields 154
ManagePendingTransactionStatus API operation 133
ManagePendingTransactionStatus request message 133
ManagePendingTransactionStatus response
message 134
ManageRecurringPaymentsProfileStatus API
operation 154
ManageRecurringPaymentsProfileStatus request
message 154
ManageRecurringPaymentsProfileStatus response
message 154
Mass Payment request fields 135
MassPay API operation 135
MassPay request message 135
MassPay response fields 135
MassPay response message 135
MasterCard AVS response codes 277
MasterCard CVV2 response codes 279
MAXAMT request field 60
MAXFAILEDPAYMENTS request field 138, 157
MAXFAILEDPAYMENTS response field 147
MERCHANTSTOREDETAILS request field 186
METHOD req uest field 121
METHOD request field 25, 27, 32, 36, 39, 41, 51, 55,
59, 78, 92, 117, 119, 133, 135, 137, 146, 154, 155,
156, 161, 162, 164, 166, 168, 171, 185, 189
METHOD response field 58
Mexican Peso 275
MIDDLENAME request field 53, 143, 191
MIDDLENAME response field 81, 124, 167, 170
MPIVENDOR3DS request field 47
Name-Value Pair API Developer Guide August 2012 303
Index
MSGSUBID request field 28, 29, 33, 172, 179, 186,
188
MULTIITEM response field 131
MXN 275
MYR 275
N
NETAMT request field 51
NETREFUNDAMT response field 187
New Zealand Dollar 275, 276
NEXTBILLINGDATE response field 151
NO_SHIPPING_OPTION_DETAILS response
field 59
NOK 275, 276
Norwegian Krone 275, 276
NOSHIPPING request field 61
NOTE request field 28, 39, 52, 154, 155, 156
NOTE response field 79, 105, 129
NOTETEXT request field 70, 97
NOTETEXT response field 86
NOTETOBUYER request field 65
NOTIFY URL request field 97
NOTIFYURL request field 45, 70, 175
NOTIFYURL response field 86
NUMCYCLESREMAINING response field 151
NUMCYCYLESCOMPLETED response field 151
NVP format 17
NZD 275, 276
O
OfferDetails response field 114
OFFERINSURANCEOPTION response field 58, 59
ORDERTIME response field 109, 125, 180
OUTSTANDINGAMT request field 157
OUTSTANDINGBALANCE response field 151
P
PAGESTYLE request field 62, 163
PAL response field 119
PARENTTRANSACTIONID re sponse field 125, 180
PAY MENTREQUEST_n_DESC request field 96
Payer Information request fields 42, 53, 143, 160, 177
Payer Information response fields 80, 123, 152, 166,
169
Payer Name request fields 53, 143, 191
Payer Name response fields 81, 124, 167, 169
PAYERBUSINESS response field 123, 166, 169
PAYERID req uest field 143
PAYERID request field 93
PAYERID response field 80, 123, 166, 169
PAYERSTATUS request field 143
PAYERSTATUS response field 80, 123, 166, 169
PAYFLOWCOLOR request field 63, 164
PAYME
NREQUEST_n_INSURANCEOPTIONOFFERE
D response field 84
Payment Details Item request fields 46, 71, 100, 144,
175, 287, 288, 290
Payment Details Item response fields 87
Payment Details request fields 43, 67, 94, 173
Payment Details response fields 83
Payment Error Type response fields 91, 115
Payment Information response fields 108, 125, 179
Payment Item Information response fields 129
Payment Request Info Type response fields 91
PAYMENTACTION reque st field 63
PAYMENTACTION request field 41, 71, 93, 98, 171,
289
PAYMENTINFO_n_AMT response field 109
PAYMENTINFO_n_CURRENCYCODE response
field 109
PAYMENTINFO_n_EBAYITEMAUCTIONTXNID
response field 113
PAYMENTINFO_n_EXCHANGERATE response
field 110
PAYMENTINFO_n_FEEAMT response field 109
PAYMENTINFO_n_HOLDDECISION response
field 112
PAYMENTINFO_n_ORDERTIME response field 109
PAYMENTINFO_n_PAYMENTSTATUS response
field 110
PAYMENTINFO_n_PAYMENTTYPE response
field 108
PAYMENTINFO_n_PENDINGREASON response
field 111
PAYMENTINFO_n_PROTECTIONELIGIBILITY
response field 112
PAYMENTINFO_n_PROTECTIONELIGIBILITYTYP
E response field 113
PAYMENTINFO_n_REASONCODE response
field 112
PAYMENTINFO_n_TAXAMT response field 109
Index
304 August 2012 Name-Value Pair API Developer Guide
PAYMENTINFO_n_TRANSACTIONID response
field 108, 109
PAYMENTINFO_n_TRANSACTIONTYPE response
field 108
PaymentItemType response fields 130
PaymentPeriod.Amount request field 140
PaymentReason request field 65, 172
PAYMENTREQUEST_n_ACK response field 91, 115
PAYMENTREQUEST_n_ADDRESSSTATUS
response field 82
PAYMENTREQUEST_n_AL LOWE
DPAYMENTMETHOD response field 86
PAYMENTREQUEST_n_ALLOWEDPA
YMENTMETHOD request field 98
PAYMENTREQUEST_n_ALLOWEDPAYMENTMET
HOD request field 70
PAYMENTREQUEST_n_AMT request field 67, 94
PAYMENTREQUEST_n_AMT response field 83
PAYMENTREQUEST_n_CURRENCYCODE request
field 67, 94
PAYMENTREQUEST_n_CURRENCYCODE
response field 83
PAYMENTREQUEST_n_CUSTOM request field 69,
97
PAYMENTREQUEST_n_CUSTOM response field 85
PAYMENTREQUEST_n_DESC request field 69
PAYMENTREQUEST_n_DESC response field 85
PAYMENTREQUEST_n_ERRORCODE response
field 91, 115
PAYMENTREQUEST_n_HANDLINGAMT request
field 69, 96
PAYMENTREQUEST_n_HANDLINGAMT response
field 85
PAYMENTREQUEST_n_INSURANCEAMT request
field 68, 95
PAYMENTREQUEST_n_INSURANCEAMT response
field 84
PAYMENTREQUEST_n_INSURANCEOPTIONOFFE
RED request field 68, 96
PAYMENTREQUEST_n_INVNUM request field 70,
97
PAYMENTREQUEST_n_INVNUM response field 86
PAYMENTREQUEST_n_ITEMAMT request field 67,
95, 289
PAYMENTREQUEST_n_ITEMAMT respo nse
field 83
PAYMENTREQUEST_n_LONGMESSAGE response
field 91, 115
PAYMENTREQUEST_n_NOTETEXT request
field 70, 97
PAYMENTREQUEST_n_NOTETEXT response
field 86
PAYMENTREQUEST_n_NOTIFYURL request
field 70, 97
PAYMENTREQUEST_n_NOTIFYURL response
field 86
PAYMENTREQUEST_n_PAYMENTACTION request
field 71, 98, 289
PAYMENTREQUEST_n_PAYMENTREQUESTID
request field 71, 98
PAYMENTREQUEST_n_PAYMENTREQUESTID
response field 87, 91, 113
PAYMENTREQUEST_n_SECUREME R
CHANTACCOUNT ID response field 116
PAYMENTREQUEST_n_SELLERID request
field 104
PAYMENTREQUEST_n_SELLERPAYPALACCOUN
TID request field 74
PAYMENTREQUEST_n_SELLERPAYPALACCOUN
TID response field 91, 116
PAYMENTREQUEST_n_SELLERREGISTRATIOND
ATE request field 105
PAYMENTREQUEST_n_SELLERUSERNAME
request field 105
PAYMENTREQUEST_n_SEVERITYCODE response
field 91, 115
PAYMENTREQUEST_n_SHIPDISCAMT request
field 68, 95
PAYMENTREQUEST_n_SHIPDISCAMT response
field 84
PAYMENTREQUEST_n_SHIPPINGAMT request
field 68, 95
PAYMENTREQUEST_n_SHIPPINGAMT response
field 84
PAYMENTREQUEST_n_SHIPTOCITY request
field 66, 99
PAYMENTREQUEST_n_SHIPTOCITY response
field 82
PAYMENTREQUEST_n_SHIPTOCOUNTRY request
field 66, 99
PAYMENTREQUEST_n_SHIPTOCOUNTRY
response field 82
PAYMENTREQUEST_n_SHIPTONAME request
field 66, 99
PAYMENTREQUEST_n_SHIPTONAME response
field 81
PAYMENTREQUEST_n_SHIPTOPHONENUM
request field 67, 100
PAYMENTREQUEST_n_SHIPTOPHONENUM
response field 82
Name-Value Pair API Developer Guide August 2012 305
Index
PAYMENTREQUEST_n_SHIPTOSTATE request
field 66, 99
PAYMENTREQUEST_n_SHIPTOSTATE response
field 82
PAYMENTREQUEST_n_SHIPTOSTREET request
field 66, 99
PAYMENTREQUEST_n_SHIPTOSTREET response
field 81
PAYMENTREQUEST_n_SHIPTOSTREET2 request
field 66, 99
PAYMENTREQUEST_n_SHIPTOSTREET2 response
field 81
PAYMENTREQUEST_n_SHIPTOZIP request
field 66, 99
PAYMENTREQUEST_n_SHIPTOZIP response
field 82
PAYMENTREQUEST_n_SHORTMESSAGE response
field 91, 115
PAYMENTREQUEST_n_SOFTDESCRIPTOR request
field 97
PAYMENTREQUEST_n_TAXAMT request field 69,
96
PAYMENTREQUEST_n_TAXAMT response field 85
PAYMENTREQUEST_n_TRANSACTIONID request
field 70
PAYMENTREQUEST_n_TRANSACTIONID response
field 86, 91
PAYMENTREQUESTID request field 71, 98
PAYMENTREQUESTID response fie ld 87
PAYMENTREQUESTID response field 113
PAYMENTREQUESTn_TRANSACTIONID request
field 98
PAYMENTSTATUS response field 34, 37, 110, 127,
181
PAYMENTTYPE response field 105, 108, 125, 180
PAYPALADJUSTMENT response field 79
PENDIN GREASON response field 128, 182
PENDINGREASON request field 188
PENDINGREASON response field 35, 38, 111
PERIOD response field 131
Peso 275
Philippine Peso 275
PHONENUM response field 79
PHP 275
PLN 275, 276
Polish Zloty 275, 276
Pound Sterling 275, 276
PR OTECTIONELIGIBILITY response field 129, 183
previous versions 281
PROFILEID request field 146, 154, 155, 156
ProfileID request field 191
PROFILEID response field 145, 146, 155, 161
ProfileID response field 154
PROFILEREFERENCE request field 138, 156
PROFILEREFERENCE response field 147
PROFILESTARTDATE request field 138, 157
PROFILESTARTDATE response field 147
PROTECTIONELIGIBILITY response field 35, 38,
112
PROTECTIONELIGIBILITYTYPE response field 36,
39, 129, 183
R
RE DIRECTREQUIRED response field 79
REASONCODE response field 112, 128, 182
RECEIPTID request field 189
RECEIPTID response field 125, 180
Receiver Information response fields 123
RECEIVER request field 189
RECEIVERBUSINESS response field 123
RECEIVEREMAIL response field 123
RECEIVERID response field 123
RECEIVERTYPE request field 135
Recurring Payments API Operations 137
Recurring Payments Profile Details request fields 138
Recurring Payments Profile Details response fields 147
Recurring Payments Summary Details response
fields 151
RECURRING request field 45, 175, 285
REDIRECTREQUIRED response field 105
Reference Transactions API Operations 137
REFERENCEID request field 168, 171
Refund Transaction request fields 185
Refund Transaction response fields 187
REFUNDADVICE request field 186
REFUNDINFO request field 188
REFUNDITEMDETAILS request field 186
REFUNDSOURCE request field 186
REFUNDSTATUS request field 188
RefundTransaction API operation 185
RefundTransaction request message 185
RefundTransaction response message 187
REFUNDTRANSACTIONID response field 187
REFUNDTYPE request field 185, 284
REGULARAMT response field 150
Index
306 August 2012 Name-Value Pair API Developer Guide
REGULARBILLINGFREQUENCY response field 149
REGULARBILLINGPERIOD response field 149
REGULARCURRENCYCODE response field 151
REGULARSHIPPINGAMT response field 150
REGULARTAXAMT response field 151
REGULARTOTALBILLINGCYCLES response
field 149
REQCONFIRMSHIPPING request field 60, 171
RET URNURL request field 60
RETRYUNTIL request field 186
RETURNALLCURRENCIES request field 117
RETURNFMFDETAILS request field 41, 93, 171
RETURNURL request field 162
S
SALESTAX response field 129
SALUTATION request field 53, 143, 191
SALUTATION response field 81, 124, 167, 169
Schedule Details request fields 138
SEK 275, 276
Seller Details request fields 104
SELLERID request field 104
SELLERREGISTRATIONDATE re quest field 105
SELLERUSERNAME request field 105
Set Customer Billing Agreement request fields 162
Set Customer Billing Agreement response fields 165
Set ExpressCheckout request fields 59
Set ExpressCheckout response fields 78
SetCustomerBillingAgreement API operation 162
SetCustomerBillingAgreement request message 162
SetCustomerBillingAgreement response message 165
SetExpressCheckout API operation 59
SetExpressCheckout request message 59
SetExpressCheckout response message 78
SETTLEAMT response field 109, 126, 181
SGD 275, 276
Sheqel 275
Ship To Address response fields 148, 167
SHIPDISCAMT request field 44
Shipping Options request fields 76
SHIPPINGAMT reque st field 174
SHIPPINGAMT request field 44, 51, 68, 95, 157, 159
SHIPPINGAMT response field 84, 150
SHIPPINGCALCULATIONMODE response field 90,
115, 121
SHIPPINGDISCAMT r esponse field 84
SHIPPINGDISCAMT request field 68, 95
SHIPPINGOPTIONAMOUNT request field 104
SHIPPINGOPTIONAMOUNT response field 90, 115
SHIPPINGOPTIONISDEFAULT request field 104
SHIPPINGOPTIONISDEFAULT response field 90,
115
SHIPPINGOPTIONNAME request field 104
SHIPPINGOPTIONNAME response field 90, 115
ShipTo Address request fields 47, 66, 99, 141, 157, 172
ShipTo Address response fields 81
SHIPTOCITY request fie ld 57
SHIPTOCITY request field 47, 66, 99, 141, 158, 173
SHIPTOCITY response field 82, 124, 148, 153, 167
SHIPTOCOUNTRY request field 47, 57, 66, 99, 142,
158, 173
SHIPTOCOUNTRY response field 82
SHIPTOCOUNTRYCODE response field 125, 148,
153, 167
SHIPTONAME request field 47, 66, 99, 141, 157, 172
SHIPTONAME response field 81, 124, 148, 153, 167
SHIPTOPHONENUM request field 43, 47, 54, 67, 100,
142, 144, 158, 161, 173, 178
SHIPTOPHONENUM response field 82, 125, 153
SHIPTOSTATE request field 47, 57, 66, 99, 141, 158,
173
SHIPTOSTATE response field 82, 124, 148, 153, 167
SHIPTOSTRE ET2 resp onse field 124, 153
SHIPTOSTREET request field 47, 57, 66, 99, 141, 157,
173
SHIPTOSTREET response f ield 148, 167
SHIPTOSTREET response field 81, 124, 153
SHIPTOSTREET2 request field 47, 57, 66, 99, 141,
158, 173
SHIPTOSTREET2 response field 81, 148, 167
SHIPTOZIP request field 47, 57, 66, 99, 142, 158, 173
SHIPTOZIP response field 82, 124, 148, 153, 167
Singapore Dollar 275, 276
SOFTDESCRIPTOR request field 28, 97, 172
SOLUTIONTYPE request field 63
STARTDATE request field 42, 52, 142, 160, 177, 189,
190
STARTDATE response field 152
state and proivince codes 271
STATE request field 43, 53, 144, 161, 178
STATUS request field 191
STATUS response field 134, 146
StoreId 113, 129, 183
STOREID request field 29, 186, 283, 284
Name-Value Pair API Developer Guide August 2012 307
Index
STREET request field 25, 43, 53, 143, 160, 178
STREET2 request field 43, 53, 143, 160, 178
STREETMATCH response field 26
SUBSCRIBERNAME request field 138, 156
SUBSCRIBERNAME response field 147
Subscription Terms response fields 131
SUCCESSPAGEREDIRECTREQUESTED response
field 106
SUFFIX request field 53, 143, 191
SUFFIX response field 81, 124, 167, 170
SURVEYCHOICESELECTED request field 93
SURVEYCHOICESELECTED response field 80, 123
SURVEYENABLE request field 65
SURVEYQUESTION request field 65, 93
SURVEYQUESTION response field 80, 122
Swedish Krona 275, 276
Swiss Franc 275, 276
T
Taiwan New Dollar 275
TAXAMT request field 44, 51, 69, 96, 157, 159, 174
TAXAMT response fie ld 109
TAXAMT response field 85, 126, 150, 181
TAXIDDETAILS request field 78
TAXIDDETAILS response field 92
TaxIdDetailsType request fields 78
TaxIdDetailsType response fields 92
TAXIDTYPE request field 78
TAXIDTYPE response field 92
TerminalId 113, 129, 183
TERMINALID response field 29, 187, 283, 284
Thai Baht 276
THB 276
TOKEN request field 55, 79, 92, 137, 161, 166
TOKEN response field 26, 78, 79, 105, 165
TOTALBILLINGCYCLES request field 139, 158
TOTALBILLINGCYCLES response field 149
TOTALREFUNDEDAMT response field 187
TOTALTYPE request field 65
Transaction Search request fields 189
Transaction Search response fields 192
TRANSACTIONCLASS request field 190
TRANSACTIONENTITY request field 33
TRANSACTIONID request field 32, 70, 98, 121, 133,
185, 189
TRANSACTIONID response field 33, 48, 54, 86, 108,
125, 134, 179
TransactionSearch API operation 189
TransactionSearch request message 189
TransactionSearch response message 192
TRANSACTIONTYPE response field 108, 125, 180
TRIALAMT request field 140, 159
TRIALBILLINGFREQUENCY request field 140
TRIALBILLINGPERIOD request field 139
TRIALTOTALBILLINGCYCLES request field 140,
158
TRY 276
Turkish Lira 276
TWD 275
U
U.S. Dollar 276
Update Recurring Payments Profile request fields 156
Update Recurring Payments Profile response fields 161
UpdateRecurringPaymentsProfile API operation 156
UpdateRecurringPaymentsProfile request message 156
UpdateRecurringPaymentsProfile response
message 161
URL-encoding 20
USD 276
User Selected Options response fields 90, 115
V
Visa AVS response codes 277
Visa CVV2 response codes 279
VPAS response field 50
X
XID request field 48
Y
Yen 275, 276
Z
ZIP request field 25, 43, 54, 144, 161, 178
ZIPMATCH response field 26
Zloty 275, 276
Index
308 August 2012 Name-Value Pair API Developer Guide

Navigation menu