Name-Value Pair API
Developer Guide
Last updated: February 01, 2013
Name-Value Pair API Developer Guide
Document Number: 100018.en_US-201302
© 2013 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information 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.ear
Contents
What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
What's New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 1 PayPal 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
Name-Value Pair API Developer Guide February 01, 2013 3
Contents
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Payment Details Item Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Ebay Item Payment Details Item Fields . . . . . . . . . . . . . . . . . . . . . . . . . 47
Ship To Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
3D Secure Request Fields (U.K. Merchants Only) . . . . . . . . . . . . . . . . . . . 48
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
4 February 01, 2013 Name-Value Pair API Developer Guide
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. . . . . . . . . . . . . . . . . . . . . . . . .122
Receiver Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Payer Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Payer Name Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Name-Value Pair API Developer Guide February 01, 2013 5
Contents
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 . . . . . . . . . . . . . . . . . . .133
ManagePendingTransactionStatus Response Fields . . . . . . . . . . . . . . . . . .133
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 Ops 137
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 . . . . . . . . . . . . .155
BillOutstandingAmount API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
BillOutstandingAmount Request Message . . . . . . . . . . . . . . . . . . . . . . .155
BillOutstandingAmount Response Message. . . . . . . . . . . . . . . . . . . . . . .156
UpdateRecurringPaymentsProfile API Operation . . . . . . . . . . . . . . . . . . . . . .156
UpdateRecurringPaymentsProfile Request Message . . . . . . . . . . . . . . . . . .156
UpdateRecurringPaymentsProfile Response Message . . . . . . . . . . . . . . . . .161
CreateBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . .162
CreateBillingAgreement Request Message . . . . . . . . . . . . . . . . . . . . . . .162
CreateBillingAgreement API Response Message . . . . . . . . . . . . . . . . . . . .162
6 February 01, 2013 Name-Value Pair API Developer Guide
Contents
SetCustomerBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . .162
SetCustomerBillingAgreement Request Message. . . . . . . . . . . . . . . . . . . .163
SetCustomerBillingAgreement Response Message . . . . . . . . . . . . . . . . . . .166
GetBillingAgreementCustomerDetails API Operation . . . . . . . . . . . . . . . . . . . .167
GetBillingAgreementCustomerDetails Request Message . . . . . . . . . . . . . . . .167
GetBillingAgreementCustomerDetails Response Message . . . . . . . . . . . . . . .167
BAUpdate API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
BAUpdate Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
BAUpdate Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
DoReferenceTransaction API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . .171
DoReferenceTransaction Request Message . . . . . . . . . . . . . . . . . . . . . .172
DoReferenceTransaction Response Message . . . . . . . . . . . . . . . . . . . . .179
Chapter 13 RefundTransaction API Operation . . . . . . . . . . . . . 185
RefundTransaction Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
RefundTransaction Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .185
Merchant Store Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
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 . . . . . . . . . . . . . . . . . . . . . . . . . . .191
TransactionSearch Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .191
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238
Name-Value Pair API Developer Guide February 01, 2013 7
Contents
TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240
MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
Recurring Payments Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
SetCustomerBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
GetBillingAgreementCustomerDetails Errors . . . . . . . . . . . . . . . . . . . . . . . .256
CreateBillingAgreement Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .257
UpdateBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .257
DoReferenceTransaction Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258
AddressVerify API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
ManagePendingTransactionStatus API Errors . . . . . . . . . . . . . . . . . . . . . . . .268
Appendix B Countries and Regions Supported by PayPal . . . . . . 271
Appendix C State and Province Codes . . . . . . . . . . . . . . . . . 279
Appendix D Currency Codes . . . . . . . . . . . . . . . . . . . . . . 283
Appendix E AVS and CVV2 Response Codes . . . . . . . . . . . . . 287
AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
AVS Response Codes for Visa, MasterCard, Discover, and American Express . . . .287
AVS Response Codes for Maestro . . . . . . . . . . . . . . . . . . . . . . . . . . .288
CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
CVV2 Response Codes for Visa, MasterCard, Discover, and American Express . . . .289
CVV2 Response Codes for Maestro. . . . . . . . . . . . . . . . . . . . . . . . . . .289
Appendix About Previous Versions of the API . . . . . . . . . . . . 291
What's New in Version 95.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
What's New in Version 93.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
What's New in Version 92.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
What's New in Version 91.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
What's New in Version 89.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
What's New in Version 88.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292
What’s New in Version 85.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292
What’s New in Version 84.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292
New Field in RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . .292
8 February 01, 2013 Name-Value Pair API Developer Guide
Contents
New RefundInfoType in RefundTransaction Response . . . . . . . . . . . . . . . . .292
New Field in DoReferenceTransactionResponseDetailsType . . . . . . . . . . . . .293
New Field in DoDirectPaymentResponse . . . . . . . . . . . . . . . . . . . . . . . .293
What’s New in Version 82.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293
New Field in DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . .293
New MerchantStoreDetailsType in DoCapture Request. . . . . . . . . . . . . . . . .293
New Fields in RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . .294
New MerchantStoreDetailsType in RefundTransaction Request . . . . . . . . . . . .294
What’s New in Version 80.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295
New Fields in PaymentDetailsType in DoReferenceTransaction Request . . . . . . .295
What’s New in Version 74.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295
New Behavior of DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . .295
New DoExpressCheckoutPayment Error Code . . . . . . . . . . . . . . . . . . . . .296
What’s New in Version 72.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
New TaxIdDetailsType Structure in SetExpressCheckout Request . . . . . . . . . . .296
New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response . . . . . .296
What's New in Version 69 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
New PaymentDetailsItemType Structure in CreateRecurringPaymentsProfile Request 297
Changes to PaymentDetailsItemType in DoReferenceTransaction Request . . . . . .298
What's New in Version 66 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
Changes to PaymentDetailsType in SetExpressCheckout and
DoExpressCheckoutPayment Requests. . . . . . . . . . . . . . . . . . . . . . . . .299
Changes to PaymentDetailsItemTypein SetExpressCheckout and
DoExpressCheckoutPayment Requests . . . . . . . . . . . . . . . . . . . . . . . .299
Changes to PaymentDetailsItemType in GetExpressCheckoutDetails Response . . .301
Appendix Revision History . . . . . . . . . . . . . . . . . . . . . . 303
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Name-Value Pair API Developer Guide February 01, 2013 9
Contents
10 February 01, 2013 Name-Value Pair API Developer Guide
What's New
Maintenance release. See the latest version of the PayPal Merchant API Release Notes for
more information:
notes#MerchantAPI
What’s New
https://www.x.com/developers/paypal/documentation-tools/release-
Name-Value Pair API Developer Guide February 01, 2013 11
What's New
12 February 01, 2013 Name-Value Pair API Developer Guide
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
Name-Value Pair API Developer Guide February 01, 2013 13
Documentation Feedback
14 February 01, 2013 Name-Value Pair API Developer Guide
PayPal Name-Value Pair API
1
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
PayPal API Client-Server Architecture
The PayPal API uses a client-server model in which your website is a client of the PayPal
server.
Gateway Developer Guide and Reference.
A page on your website initiates an action on a PayPal API server by sending a request to the
server. The PayPal server responds with a confirmation that the requested action was taken or
indicates that an error occurred. The response might also contain additional information
related to the request. The following diagram shows the basic request-response mechanism.
For example, you might want to obtain the buyer’s shipping address from PayPal. You can
initiate a request specifying an API operation to obtain buyer details. The response from the
PayPal API server contains information about whether the request was successful. If the
operation succeeds, the response contains the requested information. In this case, the response
contains the buyer’s shipping address. If the operation fails, the response contains one or more
error messages.
Related information:
Creating an NVP Request
Responding to an NVP Response
Name-Value Pair API Developer Guide February 01, 2013 15
PayPal Name-Value Pair API Basics
1
PayPal API Client-Server Architecture
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:
16 February 01, 2013 Name-Value Pair API Developer Guide
PayPal Name-Value Pair API Basics
NVP Format
1. Invoke an API operation, such as SetExpressCheckout, that sets up the return URL to
which PayPal redirects your buyer’s browser after the buyer finishes on PayPal. Other
setup actions also can be performed by this API operation.
2. Invoke additional API operations after receiving the buyer’s permission on PayPal, for
example, GetExpressCheckoutDetails or DoExpressCheckoutPayment.
The following diagram shows the execution flow between your site and PayPal:
1
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
Name-Value Pair API Developer Guide February 01, 2013 17
PayPal Name-Value Pair API Basics
1
Creating an NVP Request
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.
Related information:
Name-Value Pair Syntax Supporting Parallel Payments
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=
18 February 01, 2013 Name-Value Pair API Developer Guide
operation
PayPal Name-Value Pair API Basics
2. Choose the appropriate version.
In most cases, you should use the latest version of the API operation.
Creating an NVP Request
1
VERSION=
version_number
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.
API_password
PWD=
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.
Name-Value Pair API Developer Guide February 01, 2013 19
PayPal Name-Value Pair API Basics
1
Creating an NVP Request
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:
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)
20 February 01, 2013 Name-Value Pair API Developer Guide
PayPal Name-Value Pair API Basics
Executing NVP API Operations
Language Method
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
PHP Encode urlencode()
Decode urldecode()
ColdFusion Encode URLEncodedFormatstring [, charset]
Decode URLDecodeurlEncodedString[, charset])
Related information:
URL Decoding
1
List Syntax for Name-Value Pairs
The PayPal API uses a special syntax for NVP fields defined as lists.
The NVP interface to the PayPal API requires a unique name for each field. In the API, lists
are prefixed by L_. To identify an element within the list, use the offset from the beginning of
the list, starting with 0 as the first element. For example, L_DESC0 is the first line of a
description, L_DESC1, is the second line, and so on.
NOTE: Not all lists follow the L_ prefix convention; however, all lists start with 0 as the first
element.
Executing NVP API Operations
You execute a PayPal NVP API operation by submitting an HTTPS POST request to a PayPal
API server, or by using cURL or another mechanism to provide secure access between the
buyer’s browser and the PayPal API server. For example, you might implement a system in
which the buyer’s browser remains a client of your server and your server becomes a client of
the PayPal API server.
Specifying a PayPal Server
You execute a PayPal API operation by submitting the request to a PayPal API server.
Name-Value Pair API Developer Guide February 01, 2013 21
PayPal Name-Value Pair API Basics
1
Responding to an NVP Response
To execute a PayPal NVP API operation, submit the request to one of the following end
points:
Server end point Description
https://api3t.sandbox.paypal.com/nvp
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
https://api.paypal.com/nvp PayPal “live” production server for use with API certificates
NOTE: You must use different API credentials for each server end point. Typically, you
Sandbox server for use with API signatures; use for testing your
API
your API
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 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:
22 February 01, 2013 Name-Value Pair API Developer Guide
Related information:
PayPal API Client-Server Architecture
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:
PayPal Name-Value Pair API Basics
Responding to an NVP Response
1
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.
Error Responses
If the ACK value is not Success, API response fields may not be returned. An error response
has the following general format.
Name-Value Pair API Developer Guide February 01, 2013 23
PayPal Name-Value Pair API Basics
1
Responding to an NVP Response
Format of an Error Response
Response Fields on
Error
Additional pass-through information may appear in the L_ERRORPARAMIDn and
L_ERRORPARAMVALUE
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_ERRORP ARAMID0=ProcessorR esponse&L_ERRORPARAMV ALUE0=
0051&AMT=10%2e40&CURRENCYCODE=USD&AVSCODE=X&CVV2MATCH=M
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
ACK=notSuccess&TIMESTAMP=date/timeOfResponse&
CORRELATIONID=
BUILD=
L_SHORTMESSAGE0=
L_LONGMESSAGE0=
L_SEVERITYCODE0=
buildNumber&L_ERRORCODE0=errorCode&
L_ERRORPARAMVALUE
debuggingToken&VERSION=VersionNo&
shortMessage&
longMessage&
severityCode
n fields. Consider the following error response:
n fields.
Multiple errors can be
returned. Each set of
errors has a different
numeric suffix, starting
with 0 and incremented
by one for each error.
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
24 February 01, 2013 Name-Value Pair API Developer Guide
AddressVerify API Operation
2
The AddressVerify API operation confirms whether a postal address and postal code match
those of the specified PayPal account holder.
AddressVerify Request Message
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.
Name-Value Pair API Developer Guide February 01, 2013 25
AddressVerify API Operation
2
AddressVerify Response Message
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
26 February 01, 2013 Name-Value Pair API Developer Guide
Authorization and Capture API
3
Operation Reference
The Authorization and Capture API operations describe the PayPal API operations related to
delayed payment settlement:
DoCapture API Operation
Captures an authorized payment.
DoCapture Request Message
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.
Name-Value Pair API Developer Guide February 01, 2013 27
Authorization and Capture API Operation Reference
3
DoCapture API Operation
Field Description
INVNUM (Optional) Your invoice number or other identification number that is displayed to
you and to the buyer in their transaction history. The value is recorded only if the
authorization you are capturing is an Express Checkout order authorization.
NOTE: This value on DoCapture overwrites a value previously set on
DoAuthorization.
Character length and limitations: 127 single-byte alphanumeric characters
NOTE (Optional) An informational note about this settlement that is displayed to the buyer
in email and in their transaction history.
Character length and limitations: 255 single-byte characters
SOFTDESCRIPTOR (Optional) Per transaction description of the payment that is passed to the buyer’s
credit card statement.
If you provide a value in this field, the full descriptor displayed on the buyer’s
statement has the following format:
<PP * | PAYPAL *><Merchant descriptor as set in the Payment
Receiving Preferences><1 space><soft descriptor>
Character length and limitations: The soft descriptor can contain only the following
characters:
Alphanumeric characters
- (dash)
* (asterisk)
. (period)
{space}
If you pass any other characters (such as “,”), PayPal returns an error code.
The soft descriptor does not include the phone number, which can be toggled between
your customer service number and PayPal’s Customer Service number.
The maximum length of the soft descriptor is 22 characters. Of this, the PayPal prefix
uses either 4 or 8 characters of the data format. Thus, the maximum length of the soft
descriptor information that you can pass in this field is:
22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment
Receiving Preferences> + 1)
For example, assume the following conditions:
The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.
The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
The soft descriptor is passed in as JanesFlowerGifts LLC.
The resulting descriptor string on the credit card is:
PAYPAL *EBAY JanesFlow
MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
28 February 01, 2013 Name-Value Pair API Developer Guide
Authorization and Capture API Operation Reference
DoCapture API Operation
Merchant Store Details 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.
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.
3
DoCapture Response Fields
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.
Payment Information Fields
Field Description
TRANSACTIONID Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters
Name-Value Pair API Developer Guide February 01, 2013 29
Authorization and Capture API Operation Reference
3
DoCapture API Operation
Field Description
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.
30 February 01, 2013 Name-Value Pair API Developer Guide
Authorization and Capture API Operation Reference
DoCapture API Operation
Field Description
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.
3
None – No status
Canceled-Reversal – This means a reversal has been canceled. For example,
you won a dispute with the customer, and the funds for the transaction that was
reversed have been returned to you.
Completed – The payment has been completed, and the funds have been added
successfully to your account balance. This is the only value status for point-ofsale transactions.
Denied – You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the PendingReason
element.
Expired – The authorization period for this payment has been reached.
Failed – The payment has failed. This happens only if the payment was made
from your customer’s bank account.
Pending – The payment is pending. See the PendingReason field for more
information.
Refunded – You refunded the payment.
Reversed – A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer. The reason for the reversal is specified in the ReasonCode element.
Processed – A payment has been accepted.
Voided – An authorization for this transaction has been voided.
Name-Value Pair API Developer Guide February 01, 2013 31
Authorization and Capture API Operation Reference
3
DoAuthorization API Operation
Field Description
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.
regulatoryreview – The payment is pending while we make sure it meets
regulatory requirements. You will be contacted again in 24-72 hours with the
outcome of the review.
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.
DoAuthorization API Operation
Authorize a payment.
DoAuthorization Request Message
DoAuthorization Request Fields
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
32 February 01, 2013 Name-Value Pair API Developer Guide
Authorization and Capture API Operation Reference
DoAuthorization API Operation
Field Description
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 (,).
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.
3
DoAuthorization Response Message
DoAuthorization Response Fields
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.
Name-Value Pair API Developer Guide February 01, 2013 33
Authorization and Capture API Operation Reference
3
DoAuthorization API Operation
AuthorizationInfo Fields
Field Description
PAYMENTSTATUS Status of the payment. It is one of the following values:
None – No status.
Canceled-Reversal – A reversal has been canceled. For example, when
you win a dispute, PayPal returns the funds for the reversal to you.
Completed – The payment has been completed, and the funds have been
added successfully to your account balance.
Denied – You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the
PendingReason element.
Expired – The authorization period for this payment has been reached.
Failed – The payment has failed. This happens only if the payment was made
from the buyer’s bank account.
In-Progress – The transaction has not terminated. For example, an
authorization may be awaiting completion.
Partially-Refunded – The payment has been partially refunded.
Pending – The payment is pending. See the PendingReason field for more
information.
Refunded – You refunded the payment.
Reversed– A payment was reversed due to a chargeback or other type of
reversal. PayPal removes the funds from your account balance and returns
them to the buyer. The ReasonCode element specifies the reason for the
reversal.
Processed – A payment has been accepted.
Voided – An authorization for this transaction has been voided.
34 February 01, 2013 Name-Value Pair API Developer Guide
Authorization and Capture API Operation Reference
DoAuthorization API Operation
Field Description
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.
regulatoryreview – The payment is pending while we make sure it meets
regulatory requirements. You will be contacted again in 24-72 hours with the
outcome of the review.
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.
3
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.
Name-Value Pair API Developer Guide February 01, 2013 35
Authorization and Capture API Operation Reference
3
DoReauthorization API Operation
Field Description
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.
DoReauthorization API Operation
DoReauthorization Request Message
DoReauthorization Request Fields
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
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. Exmples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: 38 single-byte characters
This field is available since version 94.0.
36 February 01, 2013 Name-Value Pair API Developer Guide
Authorization and Capture API Operation Reference
DoReauthorization API Operation
DoReauthorization Response Message
DoReauthorization Response Fields
Field Description
AUTHORIZATIONID New authorization identification number.
Character length and limits:19 single-byte characters
MSGSUBID 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. Exmples of this include requests due to timeouts or errors during the original
request.
Character length and limitations: 38 single-byte characters
This field is available since version 94.0.
Authorization Information Fields
3
Field Description
PAYMENTSTATUS Status of the payment. It is one of the following values:
None – No status.
Canceled-Reversal – A reversal has been canceled. For example, when
you win a dispute, PayPal returns the funds for the reversal to you.
Completed – The payment has been completed, and the funds have been
added successfully to your account balance.
Denied – You denied the payment. This happens only if the payment was
previously pending because of possible reasons described for the
PendingReason element.
Expired – The authorization period for this payment has been reached.
Failed – The payment has failed. This happens only if the payment was made
from the buyer’s bank account.
In-Progress – The transaction has not terminated. For example, an
authorization may be awaiting completion.
Partially-Refunded – The payment has been partially refunded.
Pending – The payment is pending. See the PendingReason field for more
information.
Refunded – You refunded the payment.
Reversed– A payment was reversed due to a chargeback or other type of
reversal. PayPal removes the funds from your account balance and returns
them to the buyer. The ReasonCode element specifies the reason for the
reversal.
Processed – A payment has been accepted.
Voided – An authorization for this transaction has been voided.
Name-Value Pair API Developer Guide February 01, 2013 37
Authorization and Capture API Operation Reference
3
DoReauthorization API Operation
Field Description
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.
regulatoryreview – The payment is pending while we make sure it meets
regulatory requirements. You will be contacted again in 24-72 hours with the
outcome of the review.
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.
38 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
Authorization and Capture API Operation Reference
DoVoid API Operation
3
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.
DoVoid API Operation
Void an order or an authorization.
DoVoid Request Message
DoVoid Request Fields
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
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. Exmples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: 38 single-byte characters
This field is available since version 94.0.
Name-Value Pair API Developer Guide February 01, 2013 39
Authorization and Capture API Operation Reference
3
DoVoid API Operation
DoVoid Response Message
DoVoid Response Fields
Field Description
AUTHORIZATIONID Authorization identification number you specified in the request.
Character length and limitations: 19 single-byte characters
MSGSUBID 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. Exmples of this include requests due to timeouts or errors during the original
request.
Character length and limitations: 38 single-byte characters
This field is available since version 94.0.
40 February 01, 2013 Name-Value Pair API Developer Guide
DoDirectPayment API Operation
4
The DoDirectPayment API Operation enables you to process a credit card payment.
DoDirectPayment Request Message
DoDirectPayment Request Fields
Field Description
METHOD (Required) Must be DoDirectPayment.
PAYMENTACTION (Optional) How you want to obtain payment. It is one of the following values:
Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
Sale – This is a final sale for which you are requesting payment (default).
NOTE: Order is not allowed for Direct Payment.
Character length and limit: Up to 13 single-byte alphabetic characters
IPADDRESS (Required) IP address of the buyer’s browser.
NOTE: PayPal records this IP addresses as a means to detect possible fraud.
Character length and limitations: 15 single-byte characters, including periods, for
example, 255.255.255.255
RETURNFMFDETAILS (Optional) Flag to indicate whether you want the results returned by Fraud
Management Filters. By default, you do not receive this information. It is one of the
following values:
0 – Do not receive FMF details (default).
1 – Receive FMF details.
Name-Value Pair API Developer Guide February 01, 2013 41
DoDirectPayment API Operation
4
DoDirectPayment Request Message
Credit Card Details 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
Payer Information Fields
Field Description
EMAIL (Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters
42 February 01, 2013 Name-Value Pair API Developer Guide
DoDirectPayment API Operation
DoDirectPayment Request Message
Field Description
FIRSTNAME (Conditional) Buyer’s first name is required except when the reference transaction is
run against a billing agreement. In the case of a billing agreement, the first name field
should not be used.
Character length and limitations: 25 single-byte characters
LASTNAME (Conditional) Buyer’s last name is required except when the reference transaction is
run against a billing agreement. In the case of a billing agreement, the last name field
should not be used.
Character length and limitations: 25 single-byte characters
Address Fields
Field Description
STREET (Required) First street address.
Character length and limitations: 100 single-byte characters
4
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
Name-Value Pair API Developer Guide February 01, 2013 43
DoDirectPayment API Operation
4
DoDirectPayment Request Message
Payment Details Fields
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).
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 (,).
44 February 01, 2013 Name-Value Pair API Developer Guide
DoDirectPayment API Operation
DoDirectPayment Request Message
Field Description
HANDLINGAMT (Optional) Total handling costs for this order.
NOTE: If you specify a value for HANDLINGAMT, you must also specify a value for
ITEMAMT.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TAXAMT (Optional) Sum of tax for all items in this order.
NOTE: TAXAMT is required if you specify L_TAXAMTn
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
DESC (Optional) Description of items the buyer is purchasing.
NOTE: The value you specify is available only if the transaction includes a purchase.
This field is ignored if you set up a billing agreement for a recurring payment
that is not immediately charged.
Character length and limitations: 127 single-byte alphanumeric characters
4
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.
INVNUM is equivalent to the SOAP field InvoiceID. In reports, INVNUM values are
displayed in the InvoiceID column.
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
Name-Value Pair API Developer Guide February 01, 2013 45
DoDirectPayment API Operation
4
DoDirectPayment Request Message
Field Description
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.
Payment Details Item Fields
Field Description
L_NAME
n (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_DESC
n (Optional) Item description.
Character length and limitations: 127 single-byte characters
L_AMT
n (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_NUMBER
n (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_QTY
n (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_TAXAMT
n (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 (,).
46 February 01, 2013 Name-Value Pair API Developer Guide
Ebay Item Payment Details Item Fields
Field Description
DoDirectPayment API Operation
DoDirectPayment Request Message
4
L_EBAYITEMNUMBER
L_EBAYITEMAUCTIONTX
NID
n
L_EBAYITEMORDERID
n (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
(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
n (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
Ship To Address Fields
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
Name-Value Pair API Developer Guide February 01, 2013 47
DoDirectPayment API Operation
4
DoDirectPayment Response Message
3D Secure Request Fields (U.K. Merchants Only)
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.
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.
DoDirectPayment Response Message
DoDirectPayment Response Fields
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.
48 February 01, 2013 Name-Value Pair API Developer Guide
DoDirectPayment API Operation
DoDirectPayment Response Message
Field Description
L_FMFfilterIDn Filter ID, including the filter type (PENDING, REPORT, or DENY), the filter ID, and
the entry number,
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
n, starting from 0. Filter ID is one of the following values:
4
L_FMF
filterNAMEn Filter 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=_rendercontent&content_ID=merchant/cc_compliance_error_codes
Related information:
AVS Response Codes
AVS Response Codes for Visa, MasterCard, Discover, and American Express
AVS Response Codes for Maestro
Name-Value Pair API Developer Guide February 01, 2013 49
DoDirectPayment API Operation
4
DoDirectPayment Response Message
ThreeDSecure Response Fields
Field Description
VPAS Visa Payer Authentication Service status. The value indicates whether
Verified by Visa confirms that the information received is acceptable. It is
eturned only for Verified by Visa transactions.
Authentication:
Good result – 2 or D
Bad result – 1
Attempted authentication:
Good result – 3, 6, 8, A, or C
Bad result – 4, 7, or 9
No liability shift: Blank, 0, or B
ECISUBMITTED3DS Electronic Commerce Indicator (ECI) that PayPal submitted with the
payment authorisation request. This might not be the same value received
from the merchant. In rare cases, PayPal is required to use a different ECI
for authorisation based on the full set of 3-D Secure values provided from
the cmpi_authenticate request.
MasterCard:
01 – Merchant Liability
02 – Issuer Liability
Visa:
05 – Issuer Liability
06 – Issuer Liability
07 – Merchant Liability
50 February 01, 2013 Name-Value Pair API Developer Guide
DoNonReferencedCredit API
5
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.
Name-Value Pair API Developer Guide February 01, 2013 51
DoNonReferencedCredit API Operation
5
DoNonReferencedCredit Request Message
Field Description
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.
Credit Card Details Type 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
52 February 01, 2013 Name-Value Pair API Developer Guide
Payer Name Type Fields
Field Description
SALUTATION (Optional)Buyer's salutation.
Character length and limitations: 20 single-byte characters
FIRSTNAME (Optional)Buyer's first name.
Character length and limitations: 25 single-byte characters
MIDDLENAME (Optional)Buyer's middle name.
Character length and limitations: 25 single-byte characters
LASTNAME (Optional)Buyer's last name.
Character length and limitations: 25 single-byte characters
SUFFIX (Optional)Buyer's suffix.
Character length and limitations: 12 single-byte characters
Payer Information Fields
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message
5
Field Description
EMAIL (Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters
FIRSTNAME (Conditional) Buyer’s first name is required except when the reference transaction is
run against a billing agreement. In the case of a billing agreement, the first name field
should not be used.
Character length and limitations: 25 single-byte characters
LASTNAME (Conditional) Buyer’s last name is required except when the reference transaction is
run against a billing agreement. In the case of a billing agreement, the last name field
should not be used.
Character length and limitations: 25 single-byte characters
Address Fields
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
Name-Value Pair API Developer Guide February 01, 2013 53
DoNonReferencedCredit API Operation
5
DoNonReferencedCredit Response Message
Field Description
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
DoNonReferencedCredit Response Message
DoNonReferencedCredit Response Fields
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.
54 February 01, 2013 Name-Value Pair API Developer Guide
ExpressCheckout API Operations
6
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
Name-Value Pair API Developer Guide February 01, 2013 55
ExpressCheckout API Operations
6
Callback API Operation
Field Description
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_NAME
n Item name from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_NAME0, L_NAME1).
L_NUMBER
n Item number from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_NUMBER0, L_NUMBER1).
56 February 01, 2013 Name-Value Pair API Developer Guide
ExpressCheckout API Operations
Field Description
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_AMT
n Item unit price from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_AMT0, L_AMT1).
L_QTY
n Item unit quantity from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_QTY0, L_QTY1).
Callback API Operation
6
L_ITEMWEIGHTVALUE
L_ITEMWEIGHTUNIT
n
The weight of the item. You can pass this data to the shipping carrier as is without
n
having to make an additional database query.
These parameters must be ordered sequentially beginning with 0 (for example,
L_ITEMWEIGHTVALUE0, L_ITEMWEIGHTVALUE1).
L_ITEMHEIGHTVALUE
L_ITEMHEIGHTUNIT
n
The height of the item. You can pass this data to the shipping carrier as is without
n
having to make an additional database query.
These parameters must be ordered sequentially beginning with 0 (for example,
L_ITEMHEIGHTVALUE0, ITEMHEIGHTVALUE1).
L_ITEMWIDTHVALUE
L_ITEMWIDTHUNIT
n
The width of the item. You can pass this data to the shipping carrier as is without
n
having to make an additional database query..
These parameters must be ordered sequentially beginning with 0 (for example,
L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).
L_ITEMLENGTHVALUE
L_ITEMLENGTHUNIT
n
The length of the item. You can pass this data to the shipping carrier as is without
n
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.
Name-Value Pair API Developer Guide February 01, 2013 57
ExpressCheckout API Operations
6
Callback API Operation
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.
OFFERINSURANCEOPTION(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
E
n
L_SHIPPINGOPTIONLAB
EL
n
L_SHIPPINGOPTIONAMO
UNT
n
L_SHIPPINGOPTIONISD
EFAULT
L_TAXAMT
n (Optional) New tax amount based on this shipping option and the shipping address.
(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
(Required) The label for the shipping option as displayed to the buyer. Examples: Air:
Next Day, Expedited: 3-5 days, Ground: 5-7 days. These labels can be localized
based on the buyer’s locale, which is a part of the callback request.
These parameters must be ordered sequentially beginning with 0 (for example,
L_SHIPPINGALABEL0, L_SHIPPINGLABEL1).
Character length and limitations: 50 characters
(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.
(Required) The option that is selected by default for the buyer and is also reflected in
the “default” total.
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.
58 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
L_INSURANCEAMOUNT
OFFERINSURANCEOPTION(Optional) Indicates whether or not PayPal should display insurance in a drop-down
NO_SHIPPING_OPTION_
DETAILS
n (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.
list on the Review page. When the value is true, PayPal displays the drop-down
with the associated amount and the string ‘Yes.’
(Optional) If you do not ship to the buyer’s shipping address, set this field to 1. The
value of CALLBACKVERSION in SetExpressCheckout request must be 61.0 or
greater, similar to the following:
CALLBACKVERSION=<61.0 or greater>
Character length and limitations: string
SetExpressCheckout API Operation
The SetExpressCheckout API operation initiates an Express Checkout transaction.
SetExpressCheckout Request Message
SetExpressCheckout Request Fields
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.
Name-Value Pair API Developer Guide February 01, 2013 59
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
MAXAMT (Optional) The expected maximum total amount of the complete order, including
shipping cost and tax charges. If the transaction includes one or more one-time
purchases, this field is ignored.
For recurring payments, you should pass the expected average transaction amount
(default 25.00). PayPal uses this value to validate the buyer’s funding source.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
NOTE: This field is required when implementing the Instant Update API callback.
PayPal recommends that the maximum total amount be slightly greater than
the sum of the line-item order details, tax, and the shipping options of greatest
value.
RETURNURL (Required) URL to which the buyer’s browser is returned after choosing to pay with
PayPal. For digital goods, you must add JavaScript to this page to close the in-context
experience.
NOTE: PayPal recommends that the value be the final review page on which the
buyer confirms the order and payment or billing agreement.
Character length and limitations: 2048 single-byte characters
CANCELURL (Required) URL to which the buyer is returned if the buyer does not approve the use
of PayPal to pay you. For digital goods, you must add JavaScript to this page to close
the in-context experience.
NOTE: PayPal recommends that the value be the original page on which the buyer
chose to pay with PayPal or establish a billing agreement.
Character length and limitations: 2048 single-byte characters
CALLBACK (Optional) URL to which the callback request from PayPal is sent. It must start with
HTTPS for production integration. It can start with HTTPS or HTTP for sandbox
testing.
Character length and limitations: 1024 single-byte characters
This field is available since version 53.0.
CALLBACKTIMEOUT (Optional) An override for you to request more or less time to be able to process the
callback request and respond. The acceptable range for the override is 1 to 6 seconds.
If you specify a value greater than 6, PayPal uses the default value of 3 seconds.
Character length and limitations: An integer between 1 and 6
REQCONFIRMSHIPPING Indicates whetheror not you require the buyer’s shipping address on file with PayPal
be a confirmed address. For digital goods, this field is required, and you must set it to
0. It is one of the following values:
0 – You do not require the buyer’s shipping address be a confirmed address.
1 – You require the buyer’s shipping address be a confirmed address.
NOTE: Setting this field overrides the setting you specified in your Merchant
Account Profile.
Character length and limitations: 1 single-byte numeric character
60 February 01, 2013 Name-Value Pair API Developer Guide
ExpressCheckout API Operations
SetExpressCheckout API Operation
Field Description
NOSHIPPING Determines where or not PayPal displays shipping address fields on the PayPal pages.
For digital goods, this field is required, and you must set it to 1. It is one of the
following values:
0 – PayPal displays the shipping address on the PayPal pages.
1 – PayPal does not display shipping address fields whatsoever.
2 – If you do not pass the shipping address, PayPal obtains it from the buyer’s
account profile.
Character length and limitations: 1 single-byte numeric characters
ALLOWNOTE (Optional) Enables the buyer to enter a note to the merchant on the PayPal page
during checkout. The note is returned in the GetExpressCheckoutDetails
response and the DoExpressCheckoutPayment response. It is one of the following
values:
0 – The buyer is unable to enter a note to the merchant.
1 – The buyer is able to enter a note to the merchant.
Character length and limitations: 1 single-byte numeric character
This field is available since version 53.0.
6
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.
Name-Value Pair API Developer Guide February 01, 2013 61
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
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
62 February 01, 2013 Name-Value Pair API Developer Guide
ExpressCheckout API Operations
SetExpressCheckout API Operation
Field Description
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
6
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
Name-Value Pair API Developer Guide February 01, 2013 63
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
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
CUSTOMERSERVICENUMBER(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
64 February 01, 2013 Name-Value Pair API Developer Guide
ExpressCheckout API Operations
SetExpressCheckout API Operation
Field Description
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 (,).
BUYEREMAILOPTINENABLE(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.
6
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
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.
AddressType Fields
Field Description
PAYMENTREQUEST_
E
SHIPTONAME (deprecated)
0_SHIPTONAM
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
SHIPTONAME is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTONAME instead.
PAYMENTREQUEST_
0_SHIPTOSTR
EET
SHIPTOSTREET (deprecated)
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET instead.
PAYMENTREQUEST_
EET2
SHIPTOSTREET2 (deprecated)
0_SHIPTOSTR
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET2 instead.
Name-Value Pair API Developer Guide February 01, 2013 65
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
PAYMENTREQUEST_0_SHIPTOCIT
Y
SHIPTOCITY (deprecated)
PAYMENTREQUEST_
TE
SHIPTOSTATE (deprecated)
PAYMENTREQUEST_
SHIPTOZIP (deprecated)
PAYMENTREQUEST_
NTRYCODE
SHIPTOCOUNTRY (deprecated)
PAYMENTREQUEST_
NENUM
SHIPTOPHONENUM (deprecated)
0_SHIPTOSTA
0_SHIPTOZIP
0_SHIPTOCOU
0_SHIPTOPHO
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOCITY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCITY instead.
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTATE instead.
U.S. ZIP code or other country-specific postal code. It is required if using a
U.S. shipping address and may be required for other countries.
Character length and limitations: 20 single-byte characters
SHIPTOZIP is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOZIP instead.
Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
SHIPTOCOUNTRY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE instead.
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOPHONENUM instead.
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.
66 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
PAYMENTREQUEST_
AMT (deprecated)
PAYMENTREQUEST_
RENCYCODE
CURRENCYCODE
(deprecated)
n_AMT
n_CUR
(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.
When multiple payments are passed in one transaction, all of the payments must
have the same currency code.
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.
(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.
NOTE: When multiple payments are passed in one transaction, all of the payments
must have the same currency code.
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.
Name-Value Pair API Developer Guide February 01, 2013 67
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
PAYMENTREQUEST_n_SHI
PPINGAMT
SHIPPINGAMT (deprecated)
PAYMENTREQUEST_
n_INS
URANCEAMT
INSURANCEAMT
(deprecated)
PAYMENTREQUEST_
n_SHI
PDISCAMT
SHIPPINGDISCAMT
(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.
(Optional) Total shipping insurance costs for this order. The value must be a nonnegative 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.
(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. For
example (PAYMENTREQUEST_0_SHIPDISCAMT,
PAYMENTREQUEST_1_SHIPDISCAMT).
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_SHIPDISCAMT 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
a digit between 0 and 9, inclusive. Is one of the following values:
true – The Insurance option displays the string ‘Yes’ and the insurance
n is
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.
68 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
PAYMENTREQUEST_n_HAN
DLINGAMT
HANDLINGAMT (deprecated)
PAYMENTREQUEST_
n_TAX
AMT
TAXAMT (deprecated)
PAYMENTREQUEST_
n_DES
C
DESC (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.
(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.
(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_
TOM
CUSTOM (deprecated)
n_CUS
(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.
Name-Value Pair API Developer Guide February 01, 2013 69
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
PAYMENTREQUEST_n_INV
NUM
INVNUM (deprecated)
PAYMENTREQUEST_
n_NOT
IFYURL
NOTIFYURL (deprecated)
PAYMENTREQUEST_
n_NOT
ETEXT
NOTETEXT (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.
(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.
(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_
NSACTIONID
TRANSACTIONID
(deprecated)
n_TRA
(Optional) Transaction identification number of the transaction that was created.
You can specify up to 10 payments, where
NOTE: This field is only returned after a successful transaction for
n is a digit between 0 and 9, inclusive.
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.
70 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
PAYMENTREQUEST_
n_PAY
MENTACTION
PAYMENTACTION
(deprecated)
PAYMENTREQUEST_
n_PAY
MENTREQUESTID
PAYMENTREQUESTID
(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.
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.
Payment Details Item Type Fields
Field Description
L_PAYMENTREQUEST_
ME
m
L_NAME
n (deprecated)
n_NA
Item name. This field is required when
L_PAYMENTREQUEST_
payments, where
n_ITEMCATEGORYm is passed. You can specify up to 10
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_NAME
Use L_PAYMENTREQUEST_0_NAME
Name-Value Pair API Developer Guide February 01, 2013 71
m instead.
n is deprecated since version 63.0.
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
L_PAYMENTREQUEST_n_DE
SC
m
L_DESC
L_PAYMENTREQUEST_
T
n (deprecated)
n_AM
m
L_AMTn (deprecated)
(Optional) Item description. You can specify up to 10 payments, where
between 0 and 9, inclusive, and
m specifies the list item within the payment;
n is a digit
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_DESC
Use L_PAYMENTREQUEST_0_DESC
m instead.
n is deprecated since version 63.0.
Cost of item. This field is required when
L_PAYMENTREQUEST_
payments, where
n_ITEMCATEGORYm is passed.You can specify up to 10
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_
NOTE: If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must
specify a value for PAYMENTREQUEST_
n_AMT0, L_PAYMENTREQUEST_n_AMT1).
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_AMT
Use L_PAYMENTREQUEST_0_AMT
m instead.
n is deprecated since version 63.0.
L_PAYMENTREQUEST_
MBER
m
L_NUMBER
n (deprecated)
L_PAYMENTREQUEST_
Y
m
L_QTYn (deprecated)
n_NU
n_QT
(Optional) Item number. You can specify up to 10 payments, where
between 0 and 9, inclusive, and
m specifies the list item within the payment. These
n is a digit
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_NUMBER
63.0. Use L_PAYMENTREQUEST_0_NUMBER
n is deprecated since version
m instead.
Item quantity. This field is required when
L_PAYMENTREQUEST_
(L_PAYMENTREQUEST_
You can specify up to 10 payments, where
and
m specifies the list item within the payment; except for digital goods, which
n_ITEMCATEGORYm is passed. For digital goods
n_ITEMCATEGORYm=Digital), this field is required.
n is a digit between 0 and 9, inclusive,
only supports single payments. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
n_QTY1).
n_QTY0,
Character length and limitations: Any positive integer
This field is introduced in version 53.0. L_QTY
Use L_PAYMENTREQUEST_0_QTY
m instead.
n is deprecated since version 63.0.
72 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
L_PAYMENTREQUEST_n_TA
XAMT
m
L_TAXAMTn (deprecated)
L_PAYMENTREQUEST_
EMWEIGHTVALUE
L_PAYMENTREQUEST_
EMWEIGHTUNIT
L_ITEMWEIGHTVALUE
L_ITEMWEIGHTUNIT
n_IT
m,
n_IT
m
n and
n
(deprecated)
L_PAYMENTREQUEST_
EMLENGTHVALUE
L_PAYMENTREQUEST_
EMLENGTHUNIT
n_IT
m,
n_IT
m
L_ITEMLENGTHVALUEn and
L_ITEMLENGHTUNIT
n
(deprecated)
(Optional) Item sales tax. You can specify up to 10 payments, where
between 0 and 9, inclusive, and
m specifies the list item within the payment;
n is a digit
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_TAXAMT
L_PAYMENTREQUEST_0_TAXAMT
n is deprecated since version 63.0. Use
m instead.
(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
inclusive, and
m specifies the list item within the payment;. These parameters
n is a digit between 0 and 9,
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
n_ITEMWEIGHTVALUE0,
n_ITEMWEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMWEIGHTTVALUE
version 63.0. Use L_PAYMENTREQUEST_0_ITEMWEIGHTVALUE
L_PAYMENTREQUEST_0_ITEMWEIGHTUNIT
n and L_ITEMWEIGHTUNITn are deprecated since
m and
m instead.
(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
inclusive, and
m specifies the list item within the payment. These parameters must
n is a digit between 0 and 9,
be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
n_ITEMLENGTHVALUE0,
n_ITEMLENGTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMLENGTHVALUE
63.0. Use L_PAYMENTREQUEST_0_ITEMLENGTHVALUE
L_PAYMENTREQUEST_0_ITEMLENGTHUNIT
n and L_ITEMLENGTHUNITm are deprecated since version
m and
n instead.
L_PAYMENTREQUEST_
EMWIDTHVALUE
L_PAYMENTREQUEST_
EMWIDTHUNIT
m
L_ITEMWIDTHVALUEn and
L_ITEMWIDTHUNIT
(deprecated)
m,
n
n_IT
n_IT
(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
and
m specifies the list item within the payment. These parameters must be
n is a digit between 0 and 9, inclusive,
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
n_ITEMWIDTHVALUE0,
n_ITEMWIDTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMWIDTHVALUE
63.0. Use L_PAYMENTREQUEST_0_ITEMWIDTHVALUE
L_PAYMENTREQUEST_
Name-Value Pair API Developer Guide February 01, 2013 73
n and L_ITEMWIDTHUNITm are deprecated since version
m and
0_ITEMWIDTHUNITn instead.
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
L_PAYMENTREQUEST_
EMHEIGHTVALUE
L_PAYMENTREQUEST_
EMHEIGHTUNIT
n_IT
m,
n_IT
m
L_ITEMHEIGHTVALUEn and
L_ITEMHEIGHTUNIT
n
(deprecated)
L_PAYMENTREQUEST_
EMURL
m
n_IT
L_ITEMURLn (deprecated)
L_PAYMENTREQUEST_
EMCATEGORY
m
n_IT
(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
inclusive, and
m specifies the list item within the payment. These parameters must
n is a digit between 0 and 9,
be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
n_ITEMHEIGHTVALUE0,
n_ITEMHEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMHEIGHTVALUE
63.0. Use L_PAYMENTREQUEST_0_ITEMHEIGHTVALUE
L_PAYMENTREQUEST_0_ITEMHEIGHTUNIT
(Optional) URL for the item. You can specify up to 10 payments, where
digit between 0 and 9, inclusive, and
n and L_ITEMHEIGHTUNITm are deprecated since version
m and
n instead.
n is a
m specifies the list item within the payment.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_
L_ITEMURL
n is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_ITEMURL
n_ITEMURL0, L_PAYMENTREQUEST_n_ITEMURL1).
m instead.
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
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_
L_PAYMENTREQUEST_
Digital
Physical
n_ITEMCATEGORY0,
n_ITEMCATEGORY1). It is one of the following values:
This field is available since version 65.1.
n
Seller Details Type Fields
Field Description
PAYMENTREQUEST_
ERPAYPALACCOUNTID
n_SELL
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
74 February 01, 2013 Name-Value Pair API Developer Guide
Ebay Item Payment Details Item Type Fields
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
L_PAYMENTREQUEST_
AYITEMNUMBER
n_EB
m
L_EBAYITEMNUMBERn
(deprecated)
L_PAYMENTREQUESST_
BAYITEMAUCTIONTXNID
n_E
m
L_EBAYITEMAUCTIONTXNI
D
n (deprecated)
L_PAYMENTREQUEST_
AYITEMORDERID
n_EB
m
L_EBAYITEMORDERIDn
(deprecated)
(Optional) Auction item number. You can specify up to 10 payments, where
digit between 0 and 9, inclusive, and
m specifies the list item within the payment.
n is a
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
n_EBAYITEMNUMBER0,
n_EBAYITEMNUMBER1).
Character length: 765 single-byte characters
L_EBAYITEMNUMBER
L_PAYMENTREQUEST_0_EBAYITEMNUMBER
n is deprecated since version 63.0. Use
m instead.
(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_
L_PAYMENTREQUEST_
n_EBAYITEMAUCTIONTXNID1).
n_EBAYITEMAUCTIONTXNID0,
Character length: 255 single-byte characters
L_EBAYAUCTIONTXNID
L_PAYMENTREQUEST_0_EBAYAUCTIONTXNID
n is deprecated since version 63.0. Use
m instead.
(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_
L_PAYMENTREQUEST_
n_EBAYITEMORDERID1).
n_EBAYITEMORDERID0,
Character length: 64 single-byte characters
L_EBAYITEMORDERID
L_PAYMENTREQUEST_0_EBAYITEMORDERID
n is deprecated since version 63.0. Use
m instead.
L_PAYMENTREQUEST_
AYCARTID
m
L_EBAYITEMCARTIDn
(deprecated)
n_EB
(Optional) The unique identifier provided by eBay for this order from the buyer.
You can specify up to 10 payments, where
and
m specifies the list item within the payment. These parameters must be
n is a digit between 0 and 9, inclusive,
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
n_EBAYITEMCARTID0,
n_EBAYITEMCARTID1).
Character length: 255 single-byte characters
L_EBAYITEMCARTID
L_PAYMENTREQUEST_0_EBAYITEMCARTID
n is deprecated since version 63.0. Use
m instead.
Buyer Details Fields
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
Name-Value Pair API Developer Guide February 01, 2013 75
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
Field Description
BUYERUSERNAME xs:string
(Optional) The user name of the user at the marketplaces site.
BUYERREGISTRATIONDATExs: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
FundingSourceDetailsType Fields
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.
Shipping Options Type Fields
Field Description
L_SHIPPINGOPTIONISDEF
AULT
n
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_SHIPPINGOPTIONNAME
n Internal name of the shipping option such as Air, Ground, Expedited, and so forth.
This field is required if you specify the Callback URL.
Character length and limitations: 50 character-string.
L_SHIPPINGOPTIONAMOUN
T
n
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 (,).
76 February 01, 2013 Name-Value Pair API Developer Guide
Billing Agreement Details Type Fields
Field Description
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
L_BILLINGTYPE
n (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
ESCRIPTION
n
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_PAYMENTTYPE
n (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
USTOM
n
(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
Name-Value Pair API Developer Guide February 01, 2013 77
ExpressCheckout API Operations
6
GetExpressCheckoutDetails API Operation
Tax Id Details Type Fields
Field Description
TAXIDTYPE Buyer’s tax ID type. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for
businesses.
This field is introduced in API version 72.0.
TAXID 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.
SetExpressCheckout Response Message
SetExpressCheckout Response Fields
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
GetExpressCheckoutDetails API Operation
The GetExpressCheckoutDetails API operation obtains information about an Express
Checkout transaction.
GetExpressCheckoutDetails Request Message
GetExpressCheckoutDetails Request Fields
Field Description
METHOD (Required) Must be GetExpressCheckoutDetails.
78 February 01, 2013 Name-Value Pair API Developer Guide
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
Field Description
TOKEN (Required) A timestamped token, the value of which was returned by
SetExpressCheckout response.
Character length and limitations: 20 single-byte characters
GetExpressCheckoutDetails Response Message
GetExpressCheckoutDetails Response Fields
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
6
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.
Name-Value Pair API Developer Guide February 01, 2013 79
ExpressCheckout API Operations
6
GetExpressCheckoutDetails API Operation
Field Description
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
PaymentActionCompleted
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
SURVEYCHOICESELECTEDSurvey response the buyer selects on the PayPal pages.
Character length and limitations: 15 single-byte characters
Payer Information Fields
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
80 February 01, 2013 Name-Value Pair API Developer Guide
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
Field Description
COUNTRYCODE Buyer’s country of residence in the form of ISO standard 3166 two-character country
codes.
Character length and limitations: 2 single-byte characters
BUSINESS Buyer’s business name.
Character length and limitations: 127 single-byte characters
Payer Name Fields
Field Description
FIRSTNAME Buyer's first name.
Character length and limitations: 25 single-byte characters
MIDDLENAME Buyer's middle name.
Character length and limitations: 25 single-byte characters
LASTNAME Buyer's last name.
Character length and limitations: 25 single-byte characters
6
SUFFIX Buyer's suffix.
Character length and limitations: 12 single-byte characters
Address Type Fields
Field Description
PAYMENTREQUEST_
E
SHIPTONAME (deprecated)
PAYMENTREQUEST_
EET
SHIPTOSTREET (deprecated)
PAYMENTREQUEST_
EET2
SHIPTOSTREET2 (deprecated)
n_SHIPTONAM
n_SHIPTOSTR
n_SHIPTOSTR
Person’s name associated with this shipping address. You can specify up to
10 payments, where
Character length and limitations: 32 single-byte characters
SHIPTONAME is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTONAME instead.
First street address. You can specify up to 10 payments, where
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.
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.
n is a digit between 0 and 9, inclusive.
n is a digit
Name-Value Pair API Developer Guide February 01, 2013 81
ExpressCheckout API Operations
6
GetExpressCheckoutDetails API Operation
Field Description
PAYMENTREQUEST_n_SHIPTOCIT
Y
SHIPTOCITY (deprecated)
PAYMENTREQUEST_
n_SHIPTOSTA
TE
SHIPTOSTATE (deprecated)
PAYMENTREQUEST_
n_SHIPTOZIP
SHIPTOZIP (deprecated)
PAYMENTREQUEST_
n_SHIPTOCOU
NTRYCODE
SHIPTOCOUNTRY (deprecated)
PAYMENTREQUEST_
n_SHIPTOPHO
NENUM
SHIPTOPHONENUM (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.
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.
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.
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.
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_
ATUS
ADDRESSSTATUS (deprecated)
n_ADDRESSST
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.
PAYMENTREQUEST_
RMALIZATIONSTATUS
n_ADDRESSNO
The PayPal address normalization status. It can have one of the following
values:
None
Normalized
Unnormalized
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.
82 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
PAYMENTREQUEST_
n_AMT
AMT (deprecated)
PAYMENTREQUEST_
n_CURRE
NCYCODE
CURRENCYCODE (deprecated)
PAYMENTREQUEST_
n_ITEMA
MT
ITEMAMT (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.
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.
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.
Name-Value Pair API Developer Guide February 01, 2013 83
ExpressCheckout API Operations
6
GetExpressCheckoutDetails API Operation
Field Description
PAYMENTREQUEST_n_SHIPP
INGAMT
SHIPPINGAMT (deprecated)
PAYMENTREQUEST_
n_INSUR
ANCEAMT
INSURANCEAMT (deprecated)
PAYMENTREQUEST_
n_SHIPD
ISCAMT
SHIPPINGDISCAMT
(deprecated)
(Optional) Total shipping costs for this order. You can specify up to 10
payments, where
NOTE: If you specify a value for PAYMENTREQUEST_n_SHIPPINGAMT, you
n is a digit between 0 and 9, inclusive.
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.
(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.
(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.
84 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
PAYMENTREQUEST_n_HANDL
INGAMT
HANDLINGAMT (deprecated)
PAYMENTREQUEST_
n_TAXAM
T
TAXAMT (deprecated)
PAYMENTREQUEST_
n_DESC
DESC (deprecated)
(Optional) Total handling costs for this order. You can specify up to 10
payments, where
NOTE: If you specify a value for PAYMENTREQUEST_n_HANDLINGAMT, you
n is a digit between 0 and 9, inclusive.
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.
(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.
(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_
M
CUSTOM (deprecated)
n_CUSTO
(Optional) A free-form field for your own use. You can specify up to 10
payments, where
NOTE: The value you specify is available only if the transaction includes a
n is a digit between 0 and 9, inclusive.
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.
Name-Value Pair API Developer Guide February 01, 2013 85
ExpressCheckout API Operations
6
GetExpressCheckoutDetails API Operation
Field Description
PAYMENTREQUEST_n_INVNU
M
INVNUM (deprecated)
PAYMENTREQUEST_
n_NOTIF
YURL
NOTIFYURL (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.
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
IMPORTANT: The notify URL applies only to
n is a digit between 0 and 9, inclusive.
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)
PAYMENTREQUEST_
n_TRANS
ACTIONID
TRANSACTIONID (deprecated)
PAYMENTREQUEST_
n_ALLOW
EDPAYMENTMETHOD
ALLOWEDPAYMENTMETHOD
(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.
Transaction identification number of the transaction that was created.You can
specify up to 10 payments, where
NOTE: This field is only returned after a successful transaction for
n is a digit between 0 and 9, inclusive.
DoExpressCheckout has occurred.
TRANSACTIONID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_TRANSACTIONID instead.
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.
86 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
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
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.
Payment Details Item Type Fields
Field Description
L_PAYMENTREQUEST_
m
L_NAMEn (deprecated)
n_NAME
Item name. You can specify up to 10 payments, where
9, inclusive, and
goods, which only supports single payments. These parameters must be ordered
sequentially beginning with 0 (for example L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
Character length and limitations: 127 single-byte characters
L_NAME
n is deprecated in version 63.0. Use L_PAYMENTREQUEST_0_NAMEm
instead.
L_PAYMENTREQUEST_
m
L_DESCn (deprecated)
n_DESC
Item description. You can specify up to 10 payments, where
0 and 9, inclusive, and
digital goods, which only supports single payments.
Character length and limitations: 127 single-byte characters
This field is available since version 53.0. L_DESC
63.0. Use L_PAYMENTREQUEST_0_DESC
n is
n is a digit between 0 and
m specifies the list item within the payment; except for digital
n_NAME0,
n_NAME1).
n is a digit between
m specifies the list item within the payment; except for
n is deprecated in version
m instead.
L_PAYMENTREQUEST_
m
L_AMTn (deprecated)
n_AMT
Cost of item. You can specify up to 10 payments, where
and 9, inclusive, and
m specifies the list item within the payment; except for
n is a digit between 0
digital goods, which only supports single payments. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_
NOTE: If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must
specify a value for PAYMENTREQUEST_
n_AMT0, L_PAYMENTREQUEST_n_AMT1).
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_AMT
n is deprecated in version 63.0. Use L_PAYMENTREQUEST_0_AMTm
instead.
Name-Value Pair API Developer Guide February 01, 2013 87
ExpressCheckout API Operations
6
GetExpressCheckoutDetails API Operation
Field Description
L_PAYMENTREQUEST_n_NUMB
ER
m
L_NUMBERn (deprecated)
L_PAYMENTREQUEST_
m
n_QTY
L_QTYn (deprecated)
L_PAYMENTREQUEST_
MT
m
n_TAXA
L_TAXAMTn (deprecated)
Item number. You can specify up to 10 payments, where
and 9, inclusive, and
m specifies the list item within the payment. These
n is a digit between 0
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_NUMBER
L_PAYMENTREQUEST_
Item quantity. You can specify up to 10 payments, where
and 9, inclusive, and
n is deprecated in version 63.0. Use
0_NUMBERm instead.
n is a digit between 0
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_QTY
n is deprecated in version 63.0. Use L_PAYMENTREQUEST_0_QTYm
instead.
Item sales tax. You can specify up to 10 payments, where
and 9, inclusive, and
m specifies the list item within the payment. These
n is a digit between 0
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_TAXAMT
L_PAYMENTREQUEST_
n is deprecated in version 63.0. Use
0_TAXAMTm instead.
L_PAYMENTREQUEST_
WEIGHTVALUE
m,
L_PAYMENTREQUEST_
WEIGHTUNIT
m
L_ITEMWEIGHTVALUE
L_ITEMWEIGHTUNIT
n_ITEM
n_ITEM
n and
n
(deprecated)
L_PAYMENTREQUEST_
LENGTHVALUE
m,
L_PAYMENTREQUEST_
LENGTHUNIT
m
n_ITEM
n_ITEM
L_ITEMLENGTHVALUEn and
L_ITEMLENGTHUNIT
n
(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_
L_PAYMENTREQUEST_
n_ITEMWEIGHTVALUE1).
n_ITEMWEIGHTVALUE0,
Character length and limitations: Any positive integer
L_ITEMWEIGTHTVALUE
63.0. Use L_PAYMENTREQUEST_0_ITEMWEIGTHTVALUE
L_PAYMENTREQUEST_0_ITEMWEIGHTUNIT
n and L_ITEMWEIGHTUNITn are deprecated in version
m and
minstead.
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_
L_PAYMENTREQUEST_
n_ITEMLENGTHVALUE1).
n_ITEMLENGTHVALUE0,
Character length and limitations: Any positive integer
L_ITEMLENGTHVALUE
63.0. Use L_PAYMENTREQUEST_0_ITEMLENGTHVALUE
L_PAYMENTREQUEST_0_ITEMLENGTHUNIT
n and L_ITEMLENGTHUNITn are deprecated in version
m and
m instead.
88 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
L_PAYMENTREQUEST_
WIDTHVALUE
m,
L_PAYMENTREQUEST_
WIDTHUNIT
m
n_ITEM
n_ITEM
L_ITEMWIDTHVALUEn and
L_ITEMWIDTHUNIT
n
(deprecated)
L_PAYMENTREQUEST_
HEIGHTVALUE
m,
L_PAYMENTREQUEST_
HEIGHTUNIT
m
n_ITEM
n_ITEM
L_ITEMHEIGHTVALUEn and
L_ITEMHEIGHTUNIT
n
(deprecated)
L_PAYMENTREQUEST_
CATEGORY
m
n_ITEM
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_
L_PAYMENTREQUEST_
n_ITEMWIDTHVALUE1).
n_ITEMWIDTHVALUE0,
Character length and limitations: Any positive integer
L_ITEMWIDTHVALUE
63.0. Use L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
n and L_ITEMWIDTHUNITn are deprecated in version
n_ITEMWIDTHVALUEm and
n_ITEMWIDTHUNITm instead.
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_
L_PAYMENTREQUEST_
n_ITEMHEIGHTVALUE1).
n_ITEMHEIGHTVALUE0,
Character length and limitations: Any positive integer
L_ITEMHEIGHTVALUE
63.0. Use L_PAYMENTREQUEST_
L_ITEMHEIGHTUNIT
n and L_ITEMHEIGHTUNITn are deprecated in version
n_ITEMHEIGHTVALUEm and
m instead.
Indicates whether the item is digital or physical. For digital goods
(L_PAYMENTREQUEST_
You can specify up to 10 payments, where
inclusive, and
m specifies the list item within the payment. These parameters
n_ITEMCATEGORYm=Digital), this field is required.
n is a digit between 0 and 9,
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_
L_PAYMENTREQUEST_
Digital
Physical
n_ITEMCATEGORY0,
n_ITEMCATEGORY1). It is one of the following values:
This field is available since version 65.1.
EbayItemPaymentDetailsItemType Fields
Field Description
L_PAYMENTREQUEST_
AYITEMNUMBER
n_EB
m
EBAYITEMNUMBERn
(deprecated)
Name-Value Pair API Developer Guide February 01, 2013 89
Auction item number. You can specify up to 10 payments, where
between 0 and 9, inclusive, and
m specifies the list item within the payment.
Character length: 765 single-byte characters
EBAYITEMNUMBER
L_PAYMENTREQUEST_0_EBAYAUCTIONTXNID
n is deprecated since 63.0. Use
m instead.
n is a digit
ExpressCheckout API Operations
6
GetExpressCheckoutDetails API Operation
Field Description
L_PAYMENTREQUEST_
AYITEMAUCTIONTXNID
EBAYITEMAUCTIONTXNIDn
(deprecated)
n_EB
m
Auction transaction identification number. You can specify up to 10 payments,
n is a digit between 0 and 9, inclusive, and m specifies the list item within
where
the payment.
Character length: 255 single-byte characters
EBAYITEMAUCTIONTXNID
L_PAYMENTREQUEST_0_EBAYAUCTIONTXNID
L_PAYMENTREQUEST_
AYITEMORDERID
m
EBAYITEMORDERIDn
(deprecated)
n_EB
Auction order identification number. You can specify up to 10 payments, where
is a digit between 0 and 9, inclusive, and
payment.
Character length: 64 single-byte characters
EBAYITEMORDERID
L_PAYMENTREQUEST_0_EBAYITEMORDERID
L_PAYMENTREQUEST_
AYITEMCARTID
m
EBAYITEMCARTIDn
(deprecated)
n_EB
The unique identifier provided by eBay for this order from the buyer. You can
specify up to 10 payments, where
specifies the list item within the payment.
Character length: 255 single-byte characters
EBAYITEMCARTID
L_PAYMENTREQUEST_0_EBAYITEMCARTID
User Selected Options Type Fields
Field Description
n is deprecated since 63.0. Use
m instead.
n
m specifies the list item within the
n is deprecated since 63.0. Use
m instead.
n is a digit between 0 and 9, inclusive, and m
n is deprecated since 63.0. Use
m instead.
SHIPPINGCALCULATIONM
ODE
INSURANCEOPTIONSELEC
TED
SHIPPINGOPTIONISDEFA
ULT
Describes how the options that were presented to the buyer were determined. It is
one of the following values:
API - Callback
API - Flatrate
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.
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.
90 February 01, 2013 Name-Value Pair API Developer Guide
Seller Details Type Fields
Field Description
ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation
6
PAYMENTREQUEST_
PAYPALACCOUNTID
n_SELLER
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
Character length and limitations: 127 single-byte alphanumeric characters
Payment Request Info Type Fields
Field Description
PAYMENTREQUEST_
SACTIONID
n_TRAN
Transaction ID for up to 10 parallel payment requests. You can specify up to 10
payments, where
This field is available since version 64.0.
PAYMENTREQUEST_
ENTREQUESTID
n_PAYM
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.
Payment Error Type Fields
Field Description
PAYMENTINFO_
MESSAGE
n_SHORT
xs:string
Payment error short message. You can specify up to 10 payments, where
between 0 and 9, inclusive.
n is a digit between 0 and 9, inclusive.
n is a digit between 0 and 9, inclusive.
n is a digit
PAYMENTINFO_
ESSAGE
n_LONGM
xs:string
Payment error long message. You can specify up to 10 payments, where
n is a digit
between 0 and 9, inclusive.
PAYMENTINFO_
CODE
n_ERROR
xs:string
Payment error code. You can specify up to 10 payments, where
n is a digit between 0
and 9, inclusive.
PAYMENTINFO_
ITYCODE
n_SEVER
xs:string
Payment error severity code. You can specify up to 10 payments, where
n is a digit
between 0 and 9, inclusive.
PAYMENTINFO_
n_ACK xs:string
Application-specific error values indicating more about the error condition. You can
specify up to 10 payments, where
Name-Value Pair API Developer Guide February 01, 2013 91
n is a digit between 0 and 9, inclusive.
ExpressCheckout API Operations
6
DoExpressCheckoutPayment API Operation
Tax Id Details Type Fields
Field Description
TAXIDTYPE Buyer’s tax ID type. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for
businesses.
This field is introduced in API version 72.0.
TAXID 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.
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
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
92 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
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
SURVEYCHOICESELECTED(Optional) Survey response that the buyer selected on the PayPal pages.
Character length and limitations: 15 single-byte characters
Name-Value Pair API Developer Guide February 01, 2013 93
ExpressCheckout API Operations
6
DoExpressCheckoutPayment API Operation
Field Description
BUTTONSOURCE (Optional) Identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
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.
Field Description
PAYMENTREQUEST_
n_AMT
AMT (deprecated)
PAYMENTREQUEST_
n_CURRENC
YCODE
CURRENCYCODE (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
When multiple payments are passed in one transaction, all of the payments
must have the same currency code.
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.
(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.
NOTE: When multiple payments are passed in one transaction, all of the
payments must have the same currency code.
CURRENCYCODE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_CURRENCYCODE instead.
94 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
PAYMENTREQUEST_n_ITEMAMT
ITEMAMT (deprecated)
PAYMENTREQUEST_
n_SHIPPIN
GAMT
SHIPPINGAMT (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.
(Optional) Total shipping costs for this order. You can specify up to 10
payments, where
NOTE: If you specify a value for PAYMENTREQUEST_n_SHIPPINGAMT, you
n is a digit between 0 and 9, inclusive.
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_
CAMT
SHIPPINGDISCAMT
(deprecated)
n_SHIPDIS
(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.
Name-Value Pair API Developer Guide February 01, 2013 95
ExpressCheckout API Operations
6
DoExpressCheckoutPayment API Operation
Field Description
PAYMENTREQUEST_n_INSURAN
CEOPTIONOFFERED
INSURANCEOPTIONOFFERED
(deprecated)
PAYMENTREQUEST_
n_HANDLIN
GAMT
HANDLINGAMT (deprecated)
PAYMENTREQUEST_
n_TAXAMT
TAXAMT (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.
(Optional) Total handling costs for this order. You can specify up to 10
payments, where
NOTE: If you specify a value for PAYMENTREQUEST_n_HANDLINGAMT, you
n is a digit between 0 and 9, inclusive.
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.
(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.
PAYMENTREQUEST_
DESC (deprecated)
n_DESC
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.
(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.
96 February 01, 2013 Name-Value Pair API Developer Guide
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
PAYMENTREQUEST_n_CUSTOM
CUSTOM (deprecated)
PAYMENTREQUEST_
n_INVNUM
INVNUM (deprecated)
PAYMENTREQUEST_
n_NOTIFYU
RL
NOTIFYURL (deprecated)
(Optional) A free-form field for your own use. You can specify up to 10
payments, where
NOTE: The value you specify is available only if the transaction includes a
n is a digit between 0 and 9, inclusive.
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.
(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.
(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
IMPORTANT: The notify URL applies only to
n is a digit between 0 and 9, inclusive.
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_
T
NOTETEXT (deprecated)
n_NOTETEX
(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_
CRIPTOR
SOFTDESCRIPTOR (deprecated)
n_SOFTDES
A per transaction description of the payment that is passed to the buyer’s credit
card statement. You can specify up to 10 payments, where
n is a digit between
0 and 9, inclusive.
NOTE: Ignore when PAYMENTREQUEST_n_PAYMENTACTION=Order.
SOFTDESCRIPTOR is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SOFTDESCRIPTOR instead.
Name-Value Pair API Developer Guide February 01, 2013 97
ExpressCheckout API Operations
6
DoExpressCheckoutPayment API Operation
Field Description
PAYMENTREQUEST_n_TRANSAC
TIONID
TRANSACTIONID (deprecated)
PAYMENTREQUEST_
n_ALLOWED
PAYMENTMETHOD
ALLOWEDPAYMENTMETHOD
(deprecated)
PAYMENTREQUEST_
n_PAYMENT
ACTION
PAYMENTACTION (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.
(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.
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.
PAYMENTREQUEST_
n_PAYMENT
REQUESTID
PAYMENTREQUESTID
(deprecated)
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.
A unique identifier of the specific payment request. Required when
implementing parallel payments. You can specify up to 10 payments, where
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.
n
98 February 01, 2013 Name-Value Pair API Developer Guide
Address Fields
Field Description
ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
6
PAYMENTREQUEST_
0_SHIPTONAM
E
SHIPTONAME (deprecated)
PAYMENTREQUEST_
0_SHIPTOSTR
EET
SHIPTOSTREET (deprecated)
PAYMENTREQUEST_
0_SHIPTOSTR
EET2
SHIPTOSTREET2 (deprecated)
PAYMENTREQUEST_
0_SHIPTOCIT
Y
SHIPTOCITY (deprecated)
PAYMENTREQUEST_
0_SHIPTOSTA
TE
SHIPTOSTATE (deprecated)
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
SHIPTONAME is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTONAME instead.
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET instead.
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET2 instead.
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOCITY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCITY instead.
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTATE instead.
PAYMENTREQUEST_
SHIPTOZIP (deprecated)
0_SHIPTOZIP
U.S. ZIP code or other country-specific postal code. It is required if using a
U.S. shipping address and may be required for other countries.
Character length and limitations: 20 single-byte characters
SHIPTOZIP is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOZIP instead.
PAYMENTREQUEST_
0_SHIPTOCOU
NTRYCODE
SHIPTOCOUNTRY (deprecated)
Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
SHIPTOCOUNTRY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE instead.
PAYMENTREQUEST_
NENUM
SHIPTOPHONENUM (deprecated)
0_SHIPTOPHO
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOPHONENUM instead.
Name-Value Pair API Developer Guide February 01, 2013 99
ExpressCheckout API Operations
6
DoExpressCheckoutPayment API Operation
Payment Details Item Type Fields
Field Description
L_PAYMENTREQUEST_
ME
m
L_NAME
n (deprecated)
L_PAYMENTREQUEST_
SC
m
L_DESC
n (deprecated)
L_PAYMENTREQUEST_
T
m
L_AMTn (deprecated)
n_NA
n_DE
n_AM
Item name. This field is required when
L_PAYMENTREQUEST_
payments, where
n_ITEMCATEGORYm is passed. You can specify up to 10
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_NAME
Use L_PAYMENTREQUEST_0_NAME
m instead.
(Optional) Item description. You can specify up to 10 payments, where
between 0 and 9, inclusive, and
m specifies the list item within the payment;
n is deprecated since version 63.0.
n is a digit
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_DESC
Use L_PAYMENTREQUEST_0_DESC
m instead.
n is deprecated since version 63.0.
Cost of item. This field is required when
L_PAYMENTREQUEST_
payments, where
n_ITEMCATEGORYm is passed.You can specify up to 10
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_
NOTE: If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must
specify a value for PAYMENTREQUEST_
n_AMT0, L_PAYMENTREQUEST_n_AMT1).
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_AMT
Use L_PAYMENTREQUEST_0_AMT
m instead.
n is deprecated since version 63.0.
L_PAYMENTREQUEST_
MBER
m
L_NUMBER
n (deprecated)
n_NU
(Optional) Item number. You can specify up to 10 payments, where
between 0 and 9, inclusive, and
m specifies the list item within the payment. These
n is a digit
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_NUMBER
63.0. Use L_PAYMENTREQUEST_0_NUMBER
n is deprecated since version
m instead.
100 February 01, 2013 Name-Value Pair API Developer Guide
Loading...