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 buyers 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 buyers 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 buyers 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
buyers browser and the PayPal API server. For example, you might implement a system in
which the buyers 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 buyers
credit card statement.
If you provide a value in this field, the full descriptor displayed on the buyers
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 customers 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 buyers 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 buyers 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 buyers 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) Buyers 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) Buyers 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) Buyers 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) Buyers middle name.
Character length and limitations: 25 single-byte characters
LASTNAME (Optional) Buyers last name.
Character length and limitations: 25 single-byte characters
SUFFIX (Optional) Buyers 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) Buyers first name.
Character length and limitations: 25 single-byte characters
LASTNAME (Required) Buyers 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 buyers 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 buyers 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 buyers 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 buyers 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 buyers 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 buyers shipping address be a confirmed address.
-1 – You require the buyers 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 buyers
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.
-1The 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 Buyers 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 Buyers business name.
Character length and limitations: 127 single-byte characters
Field Description
SALUTATION Buyers salutation.
Character length and limitations: 20 single-byte characters
FIRSTNAME Buyer’s first name.
Character length and limitations: 25 single-byte characters
MIDDLENAME Buyers middle name.
Character length and limitations: 25 single-byte characters
LASTNAME Buyers last name.
Character length and limitations: 25 single-byte characters
SUFFIX Buyers 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 Buyers 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 buyers 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 ‘nis 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 ‘nis 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 ‘nis 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