Paypal Name Value Pair Api 2012 Developers Guide Developer

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

2015-07-27

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

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

Download
Open PDF In Browser	View PDF

Name-Value Pair API
Developer Guide

Last updated: August 2012

Name-Value Pair API Developer Guide
Document Number: 100018.en_US-201208

© 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

Contents

What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
What’s New in Version 93.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 1

PayPal 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

August 2012

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

Chapter 4

DoDirectPayment API Operation

. . . . . . . . . . . . . . 41

DoDirectPayment Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
DoDirectPayment Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Credit Card Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Payer Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Payment Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Payment Details Item Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Ebay Item Payment Details Item Fields . . . . . . . . . . . . . . . . . . . . . . . . . 46
Ship To Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
3D Secure Request Fields (U.K. Merchants Only) . . . . . . . . . . . . . . . . . . . 47
DoDirectPayment Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
DoDirectPayment Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
ThreeDSecure Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Chapter 5

DoNonReferencedCredit API Operation . . . . . . . . . . . 51

DoNonReferencedCredit Request Message . . . . . . . . . . . . . . . . . . . . . . . . . 51
DoNonReferencedCredit Request Fields . . . . . . . . . . . . . . . . . . . . . . . . 51
Credit Card Details Type Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Payer Name Type Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Payer Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

August 2012

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. . . . . . . . . . . . . . . . . . . . . . . . .121
Receiver Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Payer Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Payer Name Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

Name-Value Pair API Developer Guide

August 2012

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 . . . . . . . . . . . . . . . . . .134
ManagePendingTransactionStatus Response Fields . . . . . . . . . . . . . . . . . .134

Chapter 11

MassPay API Operation . . . . . . . . . . . . . . . . . . 135

MassPay Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
MassPay Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
MassPay Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
MassPay Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

Chapter 12

Recurring Payments and Reference Transactions API
Operations137

CreateRecurringPaymentsProfile API Operation . . . . . . . . . . . . . . . . . . . . . .137
CreateRecurringPaymentsProfile Request Message . . . . . . . . . . . . . . . . . .137
CreateRecurringPaymentsProfile Response Message . . . . . . . . . . . . . . . . .145
GetRecurringPaymentsProfileDetails API Operation . . . . . . . . . . . . . . . . . . . .146
GetRecurringPaymentsProfileDetails Request Message . . . . . . . . . . . . . . . .146
GetRecurringPaymentsProfileDetails Response Message . . . . . . . . . . . . . . .146
ManageRecurringPaymentsProfileStatus API Operation . . . . . . . . . . . . . . . . . .154
ManageRecurringPaymentsProfileStatus Request Message . . . . . . . . . . . . . .154
ManageRecurringPaymentsProfileStatus Response Message . . . . . . . . . . . . .154
BillOutstandingAmount API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
BillOutstandingAmount Request Message . . . . . . . . . . . . . . . . . . . . . . .155
BillOutstandingAmount Response Message. . . . . . . . . . . . . . . . . . . . . . .155
UpdateRecurringPaymentsProfile API Operation . . . . . . . . . . . . . . . . . . . . . .156
UpdateRecurringPaymentsProfile Request Message . . . . . . . . . . . . . . . . . .156
UpdateRecurringPaymentsProfile Response Message . . . . . . . . . . . . . . . . .161
CreateBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . .161
CreateBillingAgreement Request Message . . . . . . . . . . . . . . . . . . . . . . .161

August 2012

Name-Value Pair API Developer Guide

Contents

CreateBillingAgreement API Response Message . . . . . . . . . . . . . . . . . . . .162
SetCustomerBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . .162
SetCustomerBillingAgreement Request Message. . . . . . . . . . . . . . . . . . . .162
SetCustomerBillingAgreement Response Message . . . . . . . . . . . . . . . . . . .165
GetBillingAgreementCustomerDetails API Operation . . . . . . . . . . . . . . . . . . . .166
GetBillingAgreementCustomerDetails Request Message . . . . . . . . . . . . . . . .166
GetBillingAgreementCustomerDetails Response Message . . . . . . . . . . . . . . .166
BAUpdate API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
BAUpdate Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
BAUpdate Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168
DoReferenceTransaction API Operation. . . . . . . . . . . . . . . . . . . . . . . . . . .171
DoReferenceTransaction Request Message . . . . . . . . . . . . . . . . . . . . . .171
DoReferenceTransaction Response Message . . . . . . . . . . . . . . . . . . . . .178

Chapter 13

RefundTransaction API Operation . . . . . . . . . . . . . 185

RefundTransaction Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
RefundTransaction Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .185
Merchant Store Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
RefundTransaction Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . .187
RefundTransaction Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .187
RefundInfoType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188

Chapter 14

TransactionSearch API Operation . . . . . . . . . . . . . 189

TransactionSearch Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
TransactionSearch Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .189
Payer Name Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
TransactionSearch Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . .192
TransactionSearch Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .192

Appendix A API Error Codes . . . . . . . . . . . . . . . . . . . . . . 193
General API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194
DirectPayment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
SetExpressCheckout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
GetExpressCheckoutDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . .223
DoExpressCheckoutPayment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . .224
Authorization and Capture API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .233

Name-Value Pair API Developer Guide

August 2012

Contents

GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
Recurring Payments Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
SetCustomerBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
GetBillingAgreementCustomerDetails Errors . . . . . . . . . . . . . . . . . . . . . . . .253
CreateBillingAgreement Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253
UpdateBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
DoReferenceTransaction Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
AddressVerify API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262
ManagePendingTransactionStatus API Errors . . . . . . . . . . . . . . . . . . . . . . . .262

Appendix B Countries and Regions Supported by PayPal

. . . . . . 263

Appendix C State and Province Codes . . . . . . . . . . . . . . . . . 271
Appendix D Currency Codes . . . . . . . . . . . . . . . . . . . . . . 275
Appendix E AVS and CVV2 Response Codes

. . . . . . . . . . . . . 277

AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277
AVS Response Codes for Visa, MasterCard, Discover, and American Express . . . .277
AVS Response Codes for Maestro . . . . . . . . . . . . . . . . . . . . . . . . . . .278
CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279
CVV2 Response Codes for Visa, MasterCard, Discover, and American Express . . . .279
CVV2 Response Codes for Maestro. . . . . . . . . . . . . . . . . . . . . . . . . . .279

About Previous Versions of the API . . . . . . . . . . . . . . . . . . . 281
What’s New in Version 92.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
What’s New in Version 89.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
What’s New in Version 88.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
What’s New in Version 85.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
What’s New in Version 84.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
New Field in RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . .282
New RefundInfoType in RefundTransaction Response . . . . . . . . . . . . . . . . .282
New Field in DoReferenceTransactionResponseDetailsType

. . . . . . . . . . . . .282

New Field in DoDirectPaymentResponse . . . . . . . . . . . . . . . . . . . . . . . .282

August 2012

Name-Value Pair API Developer Guide

Contents

What’s New in Version 82.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .283
New Field in DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . .283
New MerchantStoreDetailsType in DoCapture Request . . . . . . . . . . . . . . . . .283
New Fields in RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . .283
New MerchantStoreDetailsType in RefundTransaction Request . . . . . . . . . . . .284
What’s New in Version 80.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
New Fields in PaymentDetailsType in DoReferenceTransaction Request . . . . . . .285
What’s New in Version 74.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
New Behavior of DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . .285
New DoExpressCheckoutPayment Error Code . . . . . . . . . . . . . . . . . . . . .285
What’s New in Version 72.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286
New TaxIdDetailsType Structure in SetExpressCheckout Request . . . . . . . . . . .286
New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response . . . . . .286
What’s New in Version 69 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
New PaymentDetailsItemType Structure in CreateRecurringPaymentsProfile Request . .
287
Changes to PaymentDetailsItemType in DoReferenceTransaction Request . . . . . .288
What’s New in Version 66 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
Changes to PaymentDetailsType in SetExpressCheckout and
DoExpressCheckoutPayment Requests. . . . . . . . . . . . . . . . . . . . . . . . .289
Changes to PaymentDetailsItemTypein SetExpressCheckout and
DoExpressCheckoutPayment Requests . . . . . . . . . . . . . . . . . . . . . . . .289
Changes to PaymentDetailsItemType in GetExpressCheckoutDetails Response . . .291

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Name-Value Pair API Developer Guide

August 2012

Contents

August 2012

Name-Value Pair API Developer Guide

What’s New

What’s New in Version 93.0
Maintenance release. New 10486 error code added for redirects when the process declines the
transaction: The transaction couldn’t be completed. Please redirect your customer to PayPal.

Name-Value Pair API Developer Guide

August 2012

What’s New in Version 93.0

August 2012

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

August 2012

Documentation Feedback

August 2012

Name-Value Pair API Developer Guide

PayPal Name-Value Pair API
Basics
The Name-Value Pair (NVP) API provides parameter-based association between request and
response fields of a message and their values. The request message is sent from your website
by the API, and a response message is returned by PayPal using a client-server model in which
your site is a client of the PayPal server.
NOT E :

The PayFlow API also uses name-value pairs to provide parameter-based association
between request and response fields of a message and their values; however, the
PayFlow API is not the same as the NVP API; for more information about the
PayFlow API, see Gateway Developer Guide and Reference.

PayPal API Client-Server Architecture
The PayPal API uses a client-server model in which your website is a client of the PayPal
server.
A page on your website initiates an action on a PayPal API server by sending a request to the
server. The PayPal server responds with a confirmation that the requested action was taken or
indicates that an error occurred. The response might also contain additional information
related to the request. The following diagram shows the basic request-response mechanism.

For example, you might want to obtain the buyer’s shipping address from PayPal. You can
initiate a request specifying an API operation to obtain buyer details. The response from the
PayPal API server contains information about whether the request was successful. If the
operation succeeds, the response contains the requested information. In this case, the response
contains the buyer’s shipping address. If the operation fails, the response contains one or more
error messages.
Related information:
Creating an NVP Request
Responding to an NVP Response

Name-Value Pair API Developer Guide

August 2012

PayPal Name-Value Pair API Basics
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
NOT E :

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:

August 2012

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:

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

August 2012

PayPal Name-Value Pair API Basics
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.

Creating an NVP Request
The Name-Value Pair request format specifies the API operation to perform, credentials that
authorize PayPal to access your account, and fields containing additional information to be
used in the request.
Related information:
PayPal API Client-Server Architecture

Specifying the PayPal API Operation
For the NVP version of the PayPal API, you must specify the name of the PayPal API
operation to execute in each request along with the version of the API operation.
The following diagram shows the API operation part of an NVP request:

A method specifies the PayPal operation you want to execute, and each method is associated
with a version. Together, the method and version define the exact behavior of the API
operation. Typically, the behavior of an API operation does not change between versions;
however, you should carefully retest your code whenever you change a version.
To specify a method and version number:
1. Choose the PayPal API operation you want to use.
METHOD=operation
2. Choose the appropriate version.
In most cases, you should use the latest version of the API operation.
VERSION=version_number

August 2012

Name-Value Pair API Developer Guide

PayPal Name-Value Pair API Basics
Creating an NVP Request

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:

IM PORT AN T :

You must protect the values for USER, PWD, and SIGNATURE in your
implementation. Consider storing these values in a secure location other than
your web server document root and setting the file permissions so that only
the system user that executes your ecommerce application can access it.

To enable PayPal to authenticate your request:
1. Specify the API username associated with your account.
USER=API_username
2. Specify the password associated with the API user name.
PWD=API_password
3. If you are using an API signature and not an API certificate, specify the API signature
associated with the API username.
SIGNATURE=API_signature
4. Optionally, you can specify the email address on file with PayPal of the third-party
merchant on whose behalf you are calling the API operation.
SUBJECT=merchantEmailAddress
NOT E :

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:

Name-Value Pair API Developer Guide

August 2012

PayPal Name-Value Pair API Basics
Creating an NVP Request

curl --insecure https://api-3t.sandbox.paypal.com/nvp -d ^
"METHOD=name^ &VERSION=XX.0^ &USER=API_username^ &PWD=API_password^
&SIGNATURE=API_signature^ &..."

This example does not establish a secure connection and should not be used live on
paypal.com.

NOT E :

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

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
ASP.NET

Classic ASP

Java

Method
Encode

System.Web.HttpUtility.UrlEncode(buffer,
Encoding.Default)

Decode

System.Web.HttpUtility.UrlDecode(buffer,
Encoding.Default)

Encode

Server.URLEncode

Decode

No built-in function. Several implementation examples are available on the
Internet.

Encode

java.net.URLEncoder.encode

Decode

java.net.URLDecoder.decode

August 2012

Name-Value Pair API Developer Guide

PayPal Name-Value Pair API Basics
Executing NVP API Operations

Language

Method

PHP

ColdFusion

Encode

urlencode()

Decode

urldecode()

Encode

URLEncodedFormatstring [, charset]

Decode

URLDecodeurlEncodedString[, charset])

Related information:
URL Decoding

List Syntax for Name-Value Pairs
The PayPal API uses a special syntax for NVP fields defined as lists.
The NVP interface to the PayPal API requires a unique name for each field. In the API, lists
are prefixed by L_. To identify an element within the list, use the offset from the beginning of
the list, starting with 0 as the first element. For example, L_DESC0 is the first line of a
description, L_DESC1, is the second line, and so on.
NOT E :

Not all lists follow the L_ prefix convention; however, all lists start with 0 as the first
element.

Executing NVP API Operations
You execute a PayPal NVP API operation by submitting an HTTPS POST request to a PayPal
API server, or by using cURL or another mechanism to provide secure access between the
buyer’s browser and the PayPal API server. For example, you might implement a system in
which the buyer’s browser remains a client of your server and your server becomes a client of
the PayPal API server.

Specifying a PayPal Server
You execute a PayPal API operation by submitting the request to a PayPal API server.
To execute a PayPal NVP API operation, submit the request to one of the following end
points:
Server end point

Description

https://api3t.sandbox.paypal.com/nvp

Sandbox server for use with API signatures; use for testing your
API

Name-Value Pair API Developer Guide

August 2012

PayPal Name-Value Pair API Basics
Responding to an NVP Response

Server end point

Description

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

PayPal “live” production server for use with API signatures

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

Sandbox server for use with API certificates; use for testing
your API

https://api.paypal.com/nvp

PayPal “live” production server for use with API certificates

NOT E :

You must use different API credentials for each server end point. Typically, you obtain
API credentials when you test in the Sandbox and then obtain another set of
credentials for the production server. You must change each API request to use the
new credentials when you go live.

Logging API Operations
You should log basic information from the request and response messages of each PayPal API
operation you execute. You must log the Correlation ID from the response message, which
identifies the API operation to PayPal and which must be provided to Merchant Technical
Support if you need their assistance with a specific transaction.
All responses to PayPal API operations contain information that may be useful for debugging
purposes. In addition to logging the Correlation ID from the response message, you can log
other information, such as the transaction ID and timestamp, to enable you to review a
transaction on the PayPal website or through the API. You could implement a scheme that logs
the entire request and response in a “verbose” mode; however, you should never log the
password from a request.

Responding to an NVP Response
The Name-Value Pair response consists of the answer to the request as well as common fields
that identify the API operation and how it was executed.
The following diagram shows fields in the response to a PayPal NVP API operation:

Related information:
PayPal API Client-Server Architecture

August 2012

Name-Value Pair API Developer Guide

PayPal Name-Value Pair API Basics
Responding to an NVP Response

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:
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.
Format of an Error Response
Response Fields on
Error

ACK=notSuccess&TIMESTAMP=date/timeOfResponse&
CORRELATIONID=debuggingToken&VERSION=VersionNo&
BUILD=buildNumber&L_ERRORCODE0=errorCode&
L_SHORTMESSAGE0=shortMessage&
L_LONGMESSAGE0=longMessage&
L_SEVERITYCODE0=severityCode

Multiple errors can be
returned. Each set of
errors has a different
numeric suffix, starting
with 0 and incremented
by one for each error.

Additional pass-through information may appear in the L_ERRORPARAMIDn and
L_ERRORPARAMVALUEn fields. Consider the following error response:
TIMESTAMP=2011%2d11%2d15T20%3a27%3a02Z&CORRELATIONID=5be53331d9700&ACK=Fail
ure&VERSION=78%2e0&BUILD=000000&L_ERRORCODE0=15005&L_SHORTMESSAGE0=Processo
r%20Decline&L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e&
L_SEVERITYCODE0=Error&L_ERRORPARAMID0=ProcessorResponse&L_ERRORPARAMVALUE0=
0051&AMT=10%2e40&CURRENCYCODE=USD&AVSCODE=X&CVV2MATCH=M

Name-Value Pair API Developer Guide

August 2012

PayPal Name-Value Pair API Basics
Responding to an NVP Response

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

PayPal only passes selected values in the L_ERRORPARAMIDn and
L_ERRORPARAMVALUEn fields.

URL Decoding
All responses to HTTP POST operations used by the PayPal NVP API must be decoded.
The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a
PayPal API server. You must decode all data returned using the HTTP protocol so that it can
be displayed properly. Most programming languages provide a way to decode strings.
Related information:
URL Encoding

August 2012

Name-Value Pair API Developer Guide

AddressVerify API Operation

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

AddressVerify Request Message

Address Verify Request Fields
Field

Description

METHOD

(Required) Must be AddressVerify.

(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

August 2012

AddressVerify API Operation
AddressVerify Response Message

A d d r e s s Ve r i f y R e s p o n s e M e s s a g e

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

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

August 2012

Name-Value Pair API Developer Guide

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

DoCapture API Operation
Captures an authorized payment.

DoCapture Request Message

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:

Name-Value Pair API Developer Guide

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

August 2012

Authorization and Capture API Operation Reference
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:
<1 space>
Character length and limitations: The soft descriptor can contain only the following
characters:
 Alphanumeric characters
 - (dash)
 * (asterisk)
 . (period)
 {space}
If you pass any other characters (such as “,”), PayPal returns an error code.
The soft descriptor does not include the phone number, which can be toggled between
your customer service number and PayPal’s Customer Service number.
The maximum length of the soft descriptor is 22 characters. Of this, the PayPal prefix
uses either 4 or 8 characters of the data format. Thus, the maximum length of the soft
descriptor information that you can pass in this field is:
22 - len() - len( + 1)
For example, assume the following conditions:
 The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.
 The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
 The soft descriptor is passed in as JanesFlowerGifts LLC.
The resulting descriptor string on the credit card is:
PAYPAL *EBAY JanesFlow

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.

August 2012

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

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

DoCapture Response Fields
Field

Description

AUTHORIZATIONID

Authorization identification number you specified in the request.
Character length and limits: 19 single-byte characters maximum

MSGSUBID

Field

Description

TRANSACTIONID

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

Name-Value Pair API Developer Guide

August 2012

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

August 2012

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:















Name-Value Pair API Developer Guide

In a successful DoCapture response for a point-of-sale authorization, the only
value value is Completed.

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

August 2012

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

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

August 2012

Name-Value Pair API Developer Guide

Authorization and Capture API Operation Reference
DoAuthorization API Operation

Field

Description

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

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

Name-Value Pair API Developer Guide

August 2012

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

August 2012

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.
 unilateral – The payment is pending because it was made to an email
address that is not yet registered or confirmed.
 verify – The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
 other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal Customer Service.
N O TE :

PROTECTIONELIGIBILITY

Name-Value Pair API Developer Guide

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

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

August 2012

Authorization and Capture API Operation Reference
DoReauthorization API Operation

Field

Description

PROTECTIONELIGIBILITY
TYPE

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

August 2012

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

Authorization Information Fields
Field

Description

PAYMENTSTATUS

Name-Value Pair API Developer Guide

August 2012

Authorization and Capture API Operation Reference
DoReauthorization API Operation

Field

Description

PENDINGREASON

PROTECTIONELIGIBILITY

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

August 2012

Name-Value Pair API Developer Guide

Authorization and Capture API Operation Reference
DoVoid API Operation

Field

Description

PROTECTIONELIGIBILITY
TYPE

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

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

Character length and limitations: 19 single-byte characters
(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

NOTE

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

Name-Value Pair API Developer Guide

August 2012

Authorization and Capture API Operation Reference
DoVoid API Operation

August 2012

Name-Value Pair API Developer Guide

DoDirectPayment API Operation

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

DoDirectPayment Request Message

DoDirectPayment Request Fields
Field

Description

METHOD

(Required) Must be DoDirectPayment.

PAYMENTACTION

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

Order is not allowed for Direct Payment.

Character length and limit: Up to 13 single-byte alphabetic characters
IPADDRESS

(Required) IP address of the buyer’s browser.
NOTE:

PayPal records this IP addresses as a means to detect possible fraud.

Character length and limitations: 15 single-byte characters, including periods, for
example, 255.255.255.255
RETURNFMFDETAILS

Name-Value Pair API Developer Guide

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

August 2012

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

(Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters

FIRSTNAME

(Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters

August 2012

Name-Value Pair API Developer Guide

DoDirectPayment API Operation
DoDirectPayment Request Message

Field

Description

LASTNAME

(Required) Buyer’s last name.
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

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

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

Name-Value Pair API Developer Guide

August 2012

DoDirectPayment API Operation
DoDirectPayment Request Message

Field

Description

ITEMAMT

(Optional) Sum of cost of all items in this order.
NOTE:

ITEMAMT is required if you specify L_AMTn.

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

If you specify a value for SHIPPINGAMT, you must also specify a value for
ITEMAMT.

(Optional) Total shipping insurance costs for this order. The value must be a nonnegative currency amount or null if you offer insurance options.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

SHIPDISCAMT

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

HANDLINGAMT

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

If you specify a value for HANDLINGAMT, you must also specify a value for
ITEMAMT.

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

TAXAMT is required if you specify L_TAXAMTn

August 2012

Name-Value Pair API Developer Guide

DoDirectPayment API Operation
DoDirectPayment Request Message

Field

Description

DESC

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

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

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

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

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

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

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

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

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

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

NOTIFYURL

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

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

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

Name-Value Pair API Developer Guide

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.

August 2012

DoDirectPayment API Operation
DoDirectPayment Request Message

Payment Details Item Fields
Field

Description

L_NAMEn

(Optional) Item name. These parameters must be ordered sequentially beginning with
0 (for example L_NAME0, L_NAME1).
Character length and limitations: 127 single-byte characters

L_DESCn

(Optional) Item description.
Character length and limitations: 127 single-byte characters

L_AMTn

(Optional) Cost of item. These parameters must be ordered sequentially beginning
with 0 (for example L_AMT0, L_AMT1).
NOTE:

If you specify a value for L_AMTn, you must specify a value for ITEMAMT.

(Optional) Item number. These parameters must be ordered sequentially beginning
with 0 (for example L_NUMBER0, L_NUMBER1).
Character length and limitations: 127 single-byte characters

L_QTYn

(Optional) Item quantity. These parameters must be ordered sequentially beginning
with 0 (for example L_QTY0, L_QTY1).
Character length and limitations: Any positive integer

L_TAXAMTn

(Optional) Item sales tax. These parameters must be ordered sequentially beginning
with 0 (for example L_TAXAMT0, L_TAXAMT1).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

Ebay Item Payment Details Item Fields

Field

Description

L_EBAYITEMNUMBERn

(Optional) Auction item number. These parameters must be ordered sequentially
beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1).
Character length: 765 single-byte characters

L_EBAYITEMAUCTIONTX
NIDn

(Optional) Auction transaction identification number. These parameters must be
ordered sequentially beginning with 0 (for example L_EBAYITEMAUCTIONTXNID0,
L_EBAYITEMAUCTIONTXNID1).
Character length: 255 single-byte characters

August 2012

Name-Value Pair API Developer Guide

DoDirectPayment API Operation
DoDirectPayment Request Message

Field

Description

L_EBAYITEMORDERIDn

(Optional) Auction order identification number. These parameters must be ordered
sequentially beginning with 0 (for example L_EBAYITEMORDERID0,
L_EBAYITEMORDERID1).
Character length: 64 single-byte characters

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

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.

Name-Value Pair API Developer Guide

August 2012

DoDirectPayment API Operation
DoDirectPayment Response Message

Field

Description

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

If the PaymentAction of the request was Authorization, the value of
TransactionID is your AuthorizationID for use with the Authorization and
Capture APIs.

Character length and limitations: 19 single-byte characters

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.

August 2012

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

L_FMFfilterNAMEn

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

August 2012

DoDirectPayment API Operation
DoDirectPayment Response Message

ThreeDSecure Response Fields
Field

Description

VPAS

Visa Payer Authentication Service status. The value indicates whether
Verified by Visa confirms that the information received is acceptable. It is
eturned only for Verified by Visa transactions.
Authentication:
 Good result – 2 or D
 Bad result – 1
Attempted authentication:
 Good result – 3, 6, 8, A, or C
 Bad result – 4, 7, or 9
No liability shift: Blank, 0, or B

ECISUBMITTED3DS

Electronic Commerce Indicator (ECI) that PayPal submitted with the
payment authorisation request. This might not be the same value received
from the merchant. In rare cases, PayPal is required to use a different ECI
for authorisation based on the full set of 3-D Secure values provided from
the cmpi_authenticate request.
MasterCard:
 01 – Merchant Liability
 02 – Issuer Liability
Visa:
 05 – Issuer Liability
 06 – Issuer Liability
 07 – Merchant Liability

August 2012

Name-Value Pair API Developer Guide

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

DoNonReferencedCredit Request Message

DoNonReferencedCredit Request Fields
Field

Description

METHOD

(Required) Must be DoNonReferencedCredit.

AMT

(Required) Total of order, including shipping, handling, and tax. Amount =
NetAmount + ShippingAmount + TaxAmount
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Must have 2 decimal places, decimal separator must be a period (.),
and the optional thousands separator must be a comma (,).

NETAMT

(Optional) Total amount of all items in this transaction.
NOTE:

The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.

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

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

The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.

Character length and limitations: The value must be zero or greater and cannot exceed
$10,000 USD in any currency. No currency symbol. Must have 2 decimal places,
decimal separator must be a period (.), and the optional thousands separator must be a
comma (,).
SHIPPINGAMT

(Optional) Total shipping costs in this transaction.
NOTE:

The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.

Character length and limitations: Value must be zero or greater and cannot exceed
$10,000 USD in any currency. No currency symbol. Must have 2 decimal places,
decimal separator must be a period (.), and the optional thousands separator must be a
comma (,). The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.

Name-Value Pair API Developer Guide

August 2012

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

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

EXPDATE

CVV2

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

August 2012

Name-Value Pair API Developer Guide

DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message

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
Field

Description

(Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters

FIRSTNAME

(Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters

LASTNAME

(Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters

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

STATE

(Required) State or province.
Character length and limitations: 40 single-byte characters

Name-Value Pair API Developer Guide

August 2012

DoNonReferencedCredit API Operation
DoNonReferencedCredit Response Message

Field

Description

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

The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations

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

Callback API Operation
Updates the PayPal Review page with shipping options, insurance, and tax information.

Callback API Request Message

Callback Request Fields
Field

Description

METHOD

(Required) Must be Callback.

TOKEN

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

CURRENCYCODE

(Required) The three-character currency code for the transaction from the Express
Checkout API. Default: USD

Name-Value Pair API Developer Guide

August 2012

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

Item name from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_NAME0, L_NAME1).

L_NUMBERn

Item number from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_NUMBER0, L_NUMBER1).

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
Callback API Operation

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_AMTn

Item unit price from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_AMT0, L_AMT1).

L_QTYn

Item unit quantity from the Express Checkout API.
These parameters must be ordered sequentially beginning with 0 (for example,
L_QTY0, L_QTY1).

L_ITEMWEIGHTVALUEn
L_ITEMWEIGHTUNITn

The weight of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
These parameters must be ordered sequentially beginning with 0 (for example,
L_ITEMWEIGHTVALUE0, L_ITEMWEIGHTVALUE1).

L_ITEMHEIGHTVALUEn
L_ITEMHEIGHTUNITn

The height of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
These parameters must be ordered sequentially beginning with 0 (for example,
L_ITEMHEIGHTVALUE0, ITEMHEIGHTVALUE1).

L_ITEMWIDTHVALUEn
L_ITEMWIDTHUNITn

The width of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query..
These parameters must be ordered sequentially beginning with 0 (for example,
L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).

L_ITEMLENGTHVALUEn
L_ITEMLENGTHUNITn

The length of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query.
These parameters must be ordered sequentially beginning with 0 (for example,
ITEMLENGTHVALUE0, ITEMLENGTHVALUE1).

SHIPTOSTREET

First street address. Required if using a shipping address.
Character length and limitations: 300 single-byte characters.

SHIPTOSTREET2

Second street address.
Character length and limitations: 300 single-byte characters.

SHIPTOCITY

Name of city. Required if using a shipping address.
Character length and limitations: 40 single-byte characters.

SHIPTOSTATE

State or province. Required if using a shipping address.
Character length and limitations: 40 single-byte characters.

SHIPTOZIP

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

SHIPTOCOUNTRY

Country code. Required if using a shipping address.
Character limit: 2 single-byte characters.

Name-Value Pair API Developer Guide

August 2012

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

OFFERINSURANCEOPTIO
N

(Optional) Indicates whether or not PayPal should display insurance in a drop-down
list on the Review page. When the value is true, PayPal displays the drop-down
with the associated amount and the string ‘Yes.’

L_SHIPPINGOPTIONNAM
En

(Required) Is the internal/system name of a shipping option, such as Air, Ground, or
Expedited.
These parameters must be ordered sequentially beginning with 0 (for example,
L_SHIPPINGOPTIONNAME0, L_SHIPPINGOPTIONNAME1).
Character length and limitations: 50 characters

L_SHIPPINGOPTIONLAB
ELn

(Required) The label for the shipping option as displayed to the buyer. Examples: Air:
Next Day, Expedited: 3-5 days, Ground: 5-7 days. These labels can be localized
based on the buyer’s locale, which is a part of the callback request.
These parameters must be ordered sequentially beginning with 0 (for example,
L_SHIPPINGALABEL0, L_SHIPPINGLABEL1).
Character length and limitations: 50 characters

L_SHIPPINGOPTIONAMO
UNTn

(Required) Is the amount for this shipping option.
These parameters must be ordered sequentially beginning with 0 (for example,
L_SHIPPINGAMOUNT0, L_SHIPPINGAMOUNT1).
N O TE :

L_SHIPPINGOPTIONISD
EFAULT

(Required) The option that is selected by default for the buyer and is also reflected in
the “default” total.

L_TAXAMTn

(Optional) New tax amount based on this shipping option and the shipping address.
N O TE :

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

L_INSURANCEAMOUNTn

(Optional) New insurance amount based on this shipping option and the shipping
address.
N O TE :

OFFERINSURANCEOPTIO
N

NO_SHIPPING_OPTION_
DETAILS

(Optional) If you do not ship to the buyer’s shipping address, set this field to 1. The
value of CALLBACKVERSION in SetExpressCheckout request must be 61.0 or
greater, similar to the following:
CALLBACKVERSION=<61.0 or greater>
Character length and limitations: string

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

August 2012

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

RETURNURL

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.

(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

August 2012

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: 4 single-byte numeric characters
ALLOWNOTE

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

ADDROVERRIDE

(Optional) Determines whether or not the PayPal pages should display the shipping
address set by you in this SetExpressCheckout request, not the shipping address on
file with PayPal for this buyer. Displaying the PayPal street address on file does not
allow the buyer to edit that address. It is one of the following values:
 0 – The PayPal pages should not display the shipping address.
 1 – The PayPal pages should display the shipping address.
Character length and limitations: 1 single-byte numeric character

CALLBACKVERSION

Name-Value Pair API Developer Guide

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.

August 2012

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

August 2012

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

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:

Name-Value Pair API Developer Guide

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

August 2012

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

GIROPAYCANCELURL

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

BANKTXNPENDINGURL

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

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

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

BRANDNAME

(Optional) A label that overrides the business name in the PayPal account on the
PayPal hosted checkout pages.
Character length and limitations: 127 single-byte alphanumeric characters

CUSTOMERSERVICENUMB
ER

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

GIFTMESSAGEENABLE

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

GIFTRECEIPTENABLE

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

GIFTWRAPENABLE

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

GIFTWRAPNAME

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

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.

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

August 2012

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

BUYEREMAILOPTINENAB
LE

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

SURVEYQUESTION

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

SURVEYENABLE

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

L_SURVEYCHOICEn

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

TOTALTYPE

(Optional) Enables display of “Estimated Total” instead of “Total” in the cart review
area. It is one of the following values:
 Total
 EstimatedTotal

Character length and limitations: 14 single-byte characters
This field is available with API Version 64.0 or later.
NOTETOBUYER

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

PAYMENTREQUEST_n_PA
YMENTREASON

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

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation
AddressType Fields
Field

Description

PAYMENTREQUEST_n_SHIPTONAM Person’s name associated with this shipping address. It is required if using a
E
shipping address. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
SHIPTONAME (deprecated)
Character length and limitations: 32 single-byte characters
SHIPTONAME is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTONAME instead.
PAYMENTREQUEST_n_SHIPTOSTR First street address. It is required if using a shipping address. You can
EET
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
SHIPTOSTREET (deprecated)
Character length and limitations: 100 single-byte characters
SHIPTOSTREET is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET instead.
PAYMENTREQUEST_n_SHIPTOSTR (Optional) Second street address. You can specify up to 10 payments, where
EET2
n is a digit between 0 and 9, inclusive.
SHIPTOSTREET2 (deprecated)
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET2 instead.
PAYMENTREQUEST_n_SHIPTOCIT Name of city. It is required if using a shipping address. You can specify up to
Y
10 payments, where n is a digit between 0 and 9, inclusive.
SHIPTOCITY (deprecated)
Character length and limitations: 40 single-byte characters
SHIPTOCITY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCITY instead.
PAYMENTREQUEST_n_SHIPTOSTA State or province. It is required if using a shipping address. You can specify
up to 10 payments, where n is a digit between 0 and 9, inclusive.
TE
SHIPTOSTATE (deprecated)
Character length and limitations: 40 single-byte characters
SHIPTOSTATE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTATE instead.
PAYMENTREQUEST_n_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. You can
SHIPTOZIP (deprecated)
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 20 single-byte characters
SHIPTOZIP is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOZIP instead.
PAYMENTREQUEST_n_SHIPTOCOU Country code. It is required if using a shipping address. You can specify up
to 10 payments, where n is a digit between 0 and 9, inclusive.
NTRYCODE
SHIPTOCOUNTRY (deprecated)
Character length and limitations: 2 single-byte characters
SHIPTOCOUNTRY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

PAYMENTREQUEST_n_SHIPTOPHO (Optional) Phone number. You can specify up to 10 payments, where n is a
NENUM
digit between 0 and 9, inclusive.
SHIPTOPHONENUM (deprecated)
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.
Field

Description

PAYMENTREQUEST_n_AMT
AMT (deprecated)

(Required) Total cost of the transaction to the buyer. If shipping cost and tax
charges are known, include them in this value. If not, this value should be the
current sub-total of the order. If the transaction includes one or more one-time
purchases, this field must be equal to the sum of the purchases. Set this field to 0 if
the transaction does not include a one-time purchase such as when you set up a
billing agreement for a recurring payment that is not immediately charged. When
the field is set to 0, purchase-specific fields are ignored. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
AMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_AMT instead.

PAYMENTREQUEST_n_CUR
RENCYCODE
CURRENCYCODE
(deprecated)

(Optional) A 3-character currency code (default is USD). You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
CURRENCYCODE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_CURRENCYCODE instead.

PAYMENTREQUEST_n_ITE
MAMT
ITEMAMT (deprecated)

Sum of cost of all items in this order. For digital goods, this field is required. You
can specify up to 10 payments, where n is a digit between 0 and 9, inclusive; except
for digital goods, which supports single payments only.
NOTE:

PAYMENTREQUEST_n_ITEMAMT is required if you specify
L_PAYMENTREQUEST_n_AMTm.

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

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

PAYMENTREQUEST_n_SHI
PPINGAMT
SHIPPINGAMT (deprecated)

(Optional) Total shipping costs for this order. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive.
NOTE:

If you specify a value for PAYMENTREQUEST_n_SHIPPINGAMT, you must
also specify a value for PAYMENTREQUEST_n_ITEMAMT.

Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
SHIPPINGAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGAMT instead.
PAYMENTREQUEST_n_INS
URANCEAMT
INSURANCEAMT
(deprecated)

(Optional) Total shipping insurance costs for this order. The value must be a 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.

PAYMENTREQUEST_n_SHI
PDISCAMT
SHIPPINGDISCAMT
(deprecated)

(Optional) Shipping discount for this order, specified as a negative number. You
can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
SHIPPINGDISCAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGDISCAMT instead.

PAYMENTREQUEST_n_INS
URANCEOPTIONOFFERED
INSURANCEOPTIONOFFER
ED (deprecated)

(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal Review page. You can specify up to 10 payments, where n is
a digit between 0 and 9, inclusive. Is one of the following values:
 true – The Insurance option displays the string ‘Yes’ and the insurance
amount. If true, the total shipping insurance for this order must be a positive
number.
 false – The Insurance option displays ‘No.’
INSURANCEOPTIONOFFERED is deprecated since version 63.0. Use
PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

PAYMENTREQUEST_n_HAN
DLINGAMT
HANDLINGAMT (deprecated)

(Optional) Total handling costs for this order. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive.
NOTE:

If you specify a value for PAYMENTREQUEST_n_HANDLINGAMT, you must
also specify a value for PAYMENTREQUEST_n_ITEMAMT.

Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
HANDLINGAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_HANDLINGAMT instead.
PAYMENTREQUEST_n_TAX
AMT
TAXAMT (deprecated)

(Optional) Sum of tax for all items in this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
NOTE:

PAYMENTREQUEST_n_TAXAMT is required if you specify
L_PAYMENTREQUEST_n_TAXAMTm

Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
TAXAMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_TAXAMT
instead.
PAYMENTREQUEST_n_DES
C
DESC (deprecated)

(Optional) Description of items the buyer is purchasing. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
NOTE:

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

Character length and limitations: 127 single-byte alphanumeric characters
DESC is deprecated since version 63.0. Use PAYMENTREQUEST_0_DESC instead.
PAYMENTREQUEST_n_CUS
TOM
CUSTOM (deprecated)

(Optional) A free-form field for your own use. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive.
NOTE:

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

Character length and limitations: 256 single-byte alphanumeric characters
CUSTOM is deprecated since version 63.0. Use PAYMENTREQUEST_0_CUSTOM
instead.

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

PAYMENTREQUEST_n_INV
NUM
INVNUM (deprecated)

(Optional) Your own invoice or tracking number.You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
NOTE:

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

Character length and limitations: 256 single-byte alphanumeric characters
INVNUM is deprecated since version 63.0. Use PAYMENTREQUEST_0_INVNUM
instead.
PAYMENTREQUEST_n_NOT
IFYURL
NOTIFYURL (deprecated)

(Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL
from your Merchant Profile is used, if one exists.You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
I MP O R T ANT :

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

Character length and limitations: 2,048 single-byte alphanumeric characters
NOTIFYURL is deprecated since version 63.0. Use
PAYMENTREQUEST_0_NOTIFYURL instead.
PAYMENTREQUEST_n_NOT
ETEXT
NOTETEXT (deprecated)

(Optional) Note to the merchant. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive.
Character length and limitations: 255 single-byte characters
NOTETEXT is deprecated since version 63.0. Use PAYMENTREQUEST_0_NOTETEXT
instead.

PAYMENTREQUEST_n_TRA
NSACTIONID
TRANSACTIONID
(deprecated)

(Optional) Transaction identification number of the transaction that was created.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
NOTE:

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

TRANSACTIONID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_TRANSACTIONID instead.
PAYMENTREQUEST_n_ALL
OWEDPAYMENTMETHOD
ALLOWEDPAYMENTMETHOD
(deprecated)

(Optional) The payment method type. Specify the value InstantPaymentOnly.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
ALLOWEDPAYMENTMETHOD is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ALLOWEDPAYMENTMETHOD instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

PAYMENTREQUEST_n_PAY
MENTACTION
PAYMENTACTION
(deprecated)

How you want to obtain payment. When implementing parallel payments, this field
is required and must be set to Order. When implementing digital goods, this field
is required and must be set to Sale. You can specify up to 10 payments, where n is
a digit between 0 and 9, inclusive; except for digital goods, which supports single
payments only. If the transaction does not include a one-time purchase, this field is
ignored. It is one of the following values:
 Sale – This is a final sale for which you are requesting payment (default).
 Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
 Order – This payment is an order authorization subject to settlement with
PayPal Authorization and Capture.
NOTE:

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

Character length and limitations: Up to 13 single-byte alphabetic characters
PAYMENTACTION is deprecated since version 63.0. Use
PAYMENTREQUEST_0_PAYMENTACTION instead.
PAYMENTREQUEST_n_PAY
MENTREQUESTID
PAYMENTREQUESTID
(deprecated)

A unique identifier of the specific payment request, which is required for parallel
payments. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive.
Character length and limitations: Up to 127 single-byte characters
PAYMENTREQUESTID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_PAYMENTREQUESTID instead.

Payment Details Item Type Fields
Field

Description

L_PAYMENTREQUEST_n_NA
MEm
L_NAMEn (deprecated)

Item name. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment; except for digital goods, which supports single payments
only. These parameters must be ordered sequentially beginning with 0 (for
example L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0. L_NAMEn is deprecated since version 63.0.
Use L_PAYMENTREQUEST_0_NAMEm instead.

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

L_PAYMENTREQUEST_n_DE
SCm
L_DESCn (deprecated)

(Optional) Item description. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment;
except for digital goods, which supports single payments only. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_DESC0, L_PAYMENTREQUEST_n_DESC1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0. L_DESCn is deprecated since version 63.0.
Use L_PAYMENTREQUEST_0_DESCm instead.

L_PAYMENTREQUEST_n_AM
Tm
L_AMTn (deprecated)

Cost of item. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed.You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment; except for digital goods, which supports single payments
only. These parameters must be ordered sequentially beginning with 0 (for
example L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).
NOT E :

If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must
specify a value for PAYMENTREQUEST_n_ITEMAMT.

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

L_PAYMENTREQUEST_n_NU
MBERm
L_NUMBERn (deprecated)

(Optional) Item number. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NUMBER0, L_PAYMENTREQUEST_n_NUMBER1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0. L_NUMBERn is deprecated since version
63.0. Use L_PAYMENTREQUEST_0_NUMBERm instead.

L_PAYMENTREQUEST_n_QT
Ym
L_QTYn (deprecated)

Item quantity. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. For digital goods
(L_PAYMENTREQUEST_n_ITEMCATEGORYm=Digital), this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive,
and m specifies the list item within the payment; except for digital goods, which
only supports single payments. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_QTY0,
L_PAYMENTREQUEST_n_QTY1).
Character length and limitations: Any positive integer
This field is introduced in version 53.0. L_QTYn is deprecated since version 63.0.
Use L_PAYMENTREQUEST_0_QTYm instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

L_PAYMENTREQUEST_n_TA
XAMTm
L_TAXAMTn (deprecated)

(Optional) Item sales tax. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment;
except for digital goods, which only supports single payments. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_TAXAMT0, L_PAYMENTREQUEST_n_TAXAMT1).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
L_TAXAMTn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_TAXAMTm instead.

L_PAYMENTREQUEST_n_IT
EMWEIGHTVALUEm,
L_PAYMENTREQUEST_n_IT
EMWEIGHTUNITm
L_ITEMWEIGHTVALUEn and
L_ITEMWEIGHTUNITn
(deprecated)

(Optional) Item weight corresponds to the weight of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment;. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE0,
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMWEIGHTTVALUEn and L_ITEMWEIGHTUNITn are deprecated since
version 63.0. Use L_PAYMENTREQUEST_0_ITEMWEIGHTVALUEm and
L_PAYMENTREQUEST_0_ITEMWEIGHTUNITm instead.

L_PAYMENTREQUEST_n_IT
EMLENGTHVALUEm,
L_PAYMENTREQUEST_n_IT
EMLENGTHUNITm
L_ITEMLENGTHVALUEn and
L_ITEMLENGHTUNITn
(deprecated)

(Optional) Item length corresponds to the length of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters must
be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMLENGTHVALUE0,
L_PAYMENTREQUEST_n_ITEMLENGTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMLENGTHVALUEn and L_ITEMLENGTHUNITm are deprecated since version
63.0. Use L_PAYMENTREQUEST_0_ITEMLENGTHVALUEm and
L_PAYMENTREQUEST_0_ITEMLENGTHUNITn instead.

L_PAYMENTREQUEST_n_IT
EMWIDTHVALUEm,
L_PAYMENTREQUEST_n_IT
EMWIDTHUNITm
L_ITEMWIDTHVALUEn and
L_ITEMWIDTHUNITn
(deprecated)

(Optional) Item width corresponds to the width of the item. You can pass this data
to the shipping carrier as is without having to make an additional database query.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive,
and m specifies the list item within the payment. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMWIDTHVALUE0,
L_PAYMENTREQUEST_n_ITEMWIDTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMWIDTHVALUEn and L_ITEMWIDTHUNITm are deprecated since version
63.0. Use L_PAYMENTREQUEST_0_ITEMWIDTHVALUEm and
L_PAYMENTREQUEST_0_ITEMWIDTHUNITn instead.

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

L_PAYMENTREQUEST_n_IT
EMHEIGHTVALUEm,
L_PAYMENTREQUEST_n_IT
EMHEIGHTUNITm
L_ITEMHEIGHTVALUEn and
L_ITEMHEIGHTUNITn
(deprecated)

(Optional) Item height corresponds to the height of the item. You can pass this
data to the shipping carrier as is without having to make an additional database
query. You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters must
be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE0,
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMHEIGHTVALUEn and L_ITEMHEIGHTUNITm are deprecated since version
63.0. Use L_PAYMENTREQUEST_0_ITEMHEIGHTVALUEm and
L_PAYMENTREQUEST_0_ITEMHEIGHTUNITn instead.

L_PAYMENTREQUEST_n_IT
EMURLm
L_ITEMURLn (deprecated)

(Optional) URL for the item. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMURL0, L_PAYMENTREQUEST_n_ITEMURL1).
L_ITEMURLn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_ITEMURLm instead.

L_PAYMENTREQUEST_n_IT
EMCATEGORYm

Indicates whether an item is digital or physical. For digital goods, this field is
required and must be set to Digital. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive, and m specifies the list item within the
payment; except for digital goods, which only supports single payments. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMCATEGORY0,
L_PAYMENTREQUEST_n_ITEMCATEGORY1). It is one of the following values:
 Digital
 Physical
This field is available since version 65.1.

Seller Details Type Fields

Field

Description

PAYMENTREQUEST_n_SELL
ERPAYPALACCOUNTID

Unique identifier for the merchant. For parallel payments, this field is required and
must contain the Payer Id or the email address of the merchant. You can specify up
to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 127 single-byte alphanumeric characters

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
SetExpressCheckout API Operation

Ebay Item Payment Details Item Type Fields
Field

Description

L_PAYMENTREQUEST_n_EB
AYITEMNUMBERm
L_EBAYITEMNUMBERn
(deprecated)

(Optional) Auction item number. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive, and m specifies the list item within the payment.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_EBAYITEMNUMBER0,
L_PAYMENTREQUEST_n_EBAYITEMNUMBER1).
Character length: 765 single-byte characters
L_EBAYITEMNUMBERn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMNUMBERm instead.

L_PAYMENTREQUESST_n_E
BAYITEMAUCTIONTXNIDm
L_EBAYITEMAUCTIONTXNI
Dn (deprecated)

(Optional) Auction transaction identification number. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially beginning
with 0 (for example L_PAYMENTREQUEST_n_EBAYITEMAUCTIONTXNID0,
L_PAYMENTREQUEST_n_EBAYITEMAUCTIONTXNID1).
Character length: 255 single-byte characters
L_EBAYAUCTIONTXNIDn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYAUCTIONTXNIDm instead.

L_PAYMENTREQUEST_n_EB
AYITEMORDERIDm
L_EBAYITEMORDERIDn
(deprecated)

(Optional) Auction order identification number. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially beginning
with 0 (for example L_PAYMENTREQUEST_n_EBAYITEMORDERID0,
L_PAYMENTREQUEST_n_EBAYITEMORDERID1).
Character length: 64 single-byte characters
L_EBAYITEMORDERIDn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMORDERIDm instead.

L_PAYMENTREQUEST_n_EB
AYCARTIDm
L_EBAYITEMCARTIDn
(deprecated)

(Optional) The unique identifier provided by eBay for this order from the buyer.
You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive,
and m specifies the list item within the payment. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_EBAYITEMCARTID0,
L_PAYMENTREQUEST_n_EBAYITEMCARTID1).
Character length: 255 single-byte characters
L_EBAYITEMCARTIDn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMCARTIDm instead.

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

August 2012

ExpressCheckout API Operations
SetExpressCheckout API Operation

Field

Description

BUYERUSERNAME

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

BUYERREGISTRATIONDA
TE

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

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

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

Shipping Options Type Fields
Field

Description

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

L_SHIPPINGOPTIONNAMEn

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

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 Amount of the flat rate shipping option. This field is required if you specify the
Tn
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 (,).

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
SetExpressCheckout API Operation

Billing Agreement Details Type Fields
Field

Description

L_BILLINGTYPEn

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

BILLINGTYPE

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

L_BILLINGAGREEMENTD
ESCRIPTIONn

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

L_PAYMENTTYPEn

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

L_BILLINGAGREEMENTC
USTOMn

For recurring payments, this field is ignored.

(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

August 2012

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

TAXIDDETAILS

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

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.

August 2012

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

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

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

Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers)
or +XXX XXXXXXXX (for international numbers)
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.
N O TE :

Name-Value Pair API Developer Guide

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

August 2012

ExpressCheckout API Operations
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
 PaymentCompleted

GIFTMESSAGE

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

GIFTRECEIPTENABLE

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

GIFTWRAPNAME

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

GIFTWRAPAMOUNT

Returns the gift wrap amount only if the buyer selects the gift option on the PayPal
pages.
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Must have two decimal places, decimal separator must be a period
(.), and the optional thousands separator must be a comma (,).

BUYERMARKETINGEMAIL

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

SURVEYQUESTION

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

SURVEYCHOICESELECTE
D

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

Payer Information Fields
Field

Description

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

August 2012

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

SALUTATION

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

FIRSTNAME

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

MIDDLENAME

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

LASTNAME

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

SUFFIX

Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Address Type Fields

Field

Description

PAYMENTREQUEST_n_SHIPTONAM Person’s name associated with this shipping address. You can specify up to
E
10 payments, where n is a digit between 0 and 9, inclusive.
SHIPTONAME (deprecated)
Character length and limitations: 32 single-byte characters
SHIPTONAME is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTONAME instead.
PAYMENTREQUEST_n_SHIPTOSTR First street address. You can specify up to 10 payments, where n is a digit
EET
between 0 and 9, inclusive.
SHIPTOSTREET (deprecated)
Character length and limitations: 100 single-byte characters
SHIPTOSTREET is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTREET instead.
PAYMENTREQUEST_n_SHIPTOSTR Second street address. You can specify up to 10 payments, where n is a digit
EET2
between 0 and 9, inclusive.
SHIPTOSTREET2 (deprecated)
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

August 2012

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

PAYMENTREQUEST_n_SHIPTOCIT Name of city. You can specify up to 10 payments, where n is a digit between
Y
0 and 9, inclusive.
SHIPTOCITY (deprecated)
Character length and limitations: 40 single-byte characters
SHIPTOCITY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCITY instead.
PAYMENTREQUEST_n_SHIPTOSTA State or province. You can specify up to 10 payments, where n is a digit
TE
between 0 and 9, inclusive.
SHIPTOSTATE (deprecated)
Character length and limitations: 40 single-byte characters
SHIPTOSTATE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOSTATE instead.
PAYMENTREQUEST_n_SHIPTOZIP 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.
SHIPTOZIP (deprecated)
Character length and limitations: 20 single-byte characters
SHIPTOZIP is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOZIP instead.
PAYMENTREQUEST_n_SHIPTOCOU Country code. You can specify up to 10 payments, where n is a digit
NTRYCODE
between 0 and 9, inclusive.
SHIPTOCOUNTRY (deprecated)
Character length and limitations: 2 single-byte characters
SHIPTOCOUNTRY is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE instead.
PAYMENTREQUEST_n_SHIPTOPHO Phone number. You can specify up to 10 payments, where n is a digit
NENUM
between 0 and 9, inclusive.
SHIPTOPHONENUM (deprecated)
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPTOPHONENUM instead.
PAYMENTREQUEST_n_ADDRESSST Status of street address on file with PayPal. You can specify up to 10
ATUS
payments, where n is a digit between 0 and 9, inclusive. It is one of the
following values:
ADDRESSSTATUS (deprecated)
 none
 Confirmed
 Unconfirmed
ADDRESSSTATUS is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ADDRESSSTATUS 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.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

PAYMENTREQUEST_n_AMT
AMT (deprecated)

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
AMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_AMT instead.
PAYMENTREQUEST_n_CURRE
NCYCODE
CURRENCYCODE (deprecated)

A 3-character currency code. Default: USD.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive.
CURRENCYCODE is deprecated since version 63.0. Use
PAYMENTREQUEST_n_CURRENCYCODE instead.

PAYMENTREQUEST_n_ITEMA
MT
ITEMAMT (deprecated)

Sum of cost of all items in this order. For digital goods, this field is required.
PayPal recommends that you pass the same value in the call to
DoExpressCheckoutPayment that you passed in the call to
SetExpressCheckout. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive; except for digital goods, which supports single
payments only.
NOTE:

PAYMENTREQUEST_n_ITEMAMT is required if you specify
L_PAYMENTREQUEST_n_AMTm.

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

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

PAYMENTREQUEST_n_SHIPP
INGAMT
SHIPPINGAMT (deprecated)

(Optional) Total shipping costs for this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
NOTE:

If you specify a value for PAYMENTREQUEST_n_SHIPPINGAMT, you
must also specify a value for PAYMENTREQUEST_n_ITEMAMT.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
SHIPPINGAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGAMT instead.
PAYMENTREQUEST_n_INSUR
ANCEAMT
INSURANCEAMT (deprecated)

(Optional) Total shipping insurance costs for this order. The value must be a
non-negative currency amount or null if insurance options are offered. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
INSURANCEAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_INSURANCEAMT instead.

PAYMENTREQUEST_n_SHIPD
ISCAMT
SHIPPINGDISCAMT
(deprecated)

(Optional) Shipping discount for this order, specified as a negative number. You
can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
SHIPPINGDISCAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGDISCAMT instead.

PAYMENREQUEST_n_INSURA
NCEOPTIONOFFERED
INSURANCEOPTIONOFFERED
(deprecated)

(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal pages. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive. Is one of the following values:
 true – The Insurance option displays the string ‘Yes’ and the insurance
amount. If true, the total shipping insurance for this order must be a
positive number.
 false – The Insurance option displays ‘No.’
INSURANCEOPTIONOFFERED is deprecated since version 63.0. Use
PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

PAYMENTREQUEST_n_HANDL
INGAMT
HANDLINGAMT (deprecated)

(Optional) Total handling costs for this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
NOTE:

If you specify a value for PAYMENTREQUEST_n_HANDLINGAMT, you
must also specify a value for PAYMENTREQUEST_n_ITEMAMT.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
HANDLINGAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_HANDLINGAMT instead.
PAYMENTREQUEST_n_TAXAM
T
TAXAMT (deprecated)

PAYMENTREQUEST_n_TAXAMT is required if you specify
L_PAYMENTREQUEST_n_TAXAMTm

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

(Optional) Description of items the buyer is purchasing. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive; except for digital
goods, which supports single payments only.
NOTE:

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

Character length and limitations: 127 single-byte alphanumeric characters
DESC is deprecated since version 63.0. Use PAYMENTREQUEST_0_DESC instead.
PAYMENTREQUEST_n_CUSTO
M
CUSTOM (deprecated)

(Optional) A free-form field for your own use. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
NOTE:

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

Character length and limitations: 256 single-byte alphanumeric characters
CUSTOM is deprecated since version 63.0. Use PAYMENTREQUEST_0_CUSTOM
instead.

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

PAYMENTREQUEST_n_INVNU
M
INVNUM (deprecated)

(Optional) Your own invoice or tracking number.You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital goods,
which supports single payments only.
NOTE:

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

Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL
from your Merchant Profile is used, if one exists.
Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL
from your Merchant Profile is used, if one exists. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
I M POR T ANT :

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

Note to the merchant. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
Character length and limitations: 255 single-byte characters
NOTETEXT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_NOTETEXT instead.

PAYMENTREQUEST_n_TRANS
ACTIONID
TRANSACTIONID (deprecated)

Transaction identification number of the transaction that was created.You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
NOTE:

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

TRANSACTIONID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_TRANSACTIONID instead.
PAYMENTREQUEST_n_ALLOW
EDPAYMENTMETHOD
ALLOWEDPAYMENTMETHOD
(deprecated)

The payment method type. Specify the value InstantPaymentOnly. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
ALLOWEDPAYMENTMETHOD is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ALLOWEDPAYMENTMETHOD instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

PAYMENTREQUEST_n_PAYME
NTREQUESTID
PAYMENTREQUESTID
(deprecated)

A unique identifier of the specific payment request. Required when
implementing parallel payments. You can specify up to 10 payments, where n is
a digit between 0 and 9, inclusive.
Character length and limitations: Up to 127 single-byte characters
PAYMENTREQUESTID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_PAYMENTREQUESTID instead.

Payment Details Item Type Fields
Field

Description

L_PAYMENTREQUEST_n_NAME

Item name. You can specify up to 10 payments, where n is a digit between 0 and
9, inclusive, and m specifies the list item within the payment; except for digital
goods, which only supports single payments. These parameters must be ordered
sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_NAME0,
L_PAYMENTREQUEST_n_NAME1).
Character length and limitations: 127 single-byte characters
L_NAMEn is deprecated in version 63.0. Use L_PAYMENTREQUEST_0_NAMEm
instead.

L_NAMEn (deprecated)

L_PAYMENTREQUEST_n_DESC
m

L_DESCn (deprecated)

L_PAYMENTREQUEST_n_AMT
m

L_AMTn (deprecated)

Item description. You can specify up to 10 payments, where n is a digit between
0 and 9, inclusive, and m specifies the list item within the payment; except for
digital goods, which only supports single payments.
Character length and limitations: 127 single-byte characters
This field is available since version 53.0. L_DESCn is deprecated in version
63.0. Use L_PAYMENTREQUEST_0_DESCm instead.
Cost of item. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive, and m specifies the list item within the payment; except for
digital goods, which only supports single payments. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).
NOT E :

If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must
specify a value for PAYMENTREQUEST_n_ITEMAMT.

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

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

L_PAYMENTREQUEST_n_NUMB
ERm
L_NUMBERn (deprecated)

Item number. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NUMBER0, L_PAYMENTREQUEST_n_NUMBER1).
Character length and limitations: 127 single-byte characters
L_NUMBERn is deprecated in version 63.0. Use
L_PAYMENTREQUEST_0_NUMBERm instead.

L_PAYMENTREQUEST_n_QTY

Item quantity. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).
Character length and limitations: Any positive integer
L_QTYn is deprecated in version 63.0. Use L_PAYMENTREQUEST_0_QTYm
instead.

L_QTYn (deprecated)

L_PAYMENTREQUEST_n_TAXA
MTm
L_TAXAMTn (deprecated)

Item sales tax. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive, and m specifies the list item within the payment. These
parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_TAXAMT0, L_PAYMENTREQUEST_n_TAXAMT1).
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
L_TAXAMTn is deprecated in version 63.0. Use
L_PAYMENTREQUEST_0_TAXAMTm instead.

L_PAYMENTREQUEST_n_ITEM
WEIGHTVALUEm,
L_PAYMENTREQUEST_n_ITEM
WEIGHTUNITm
L_ITEMWEIGHTVALUEn and
L_ITEMWEIGHTUNITn
(deprecated)

Weight of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE0,
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMWEIGTHTVALUEn and L_ITEMWEIGHTUNITn are deprecated in version
63.0. Use L_PAYMENTREQUEST_0_ITEMWEIGTHTVALUEm and
L_PAYMENTREQUEST_0_ITEMWEIGHTUNITminstead.

L_PAYMENTREQUEST_n_ITEM
LENGTHVALUEm,
L_PAYMENTREQUEST_n_ITEM
LENGTHUNITm
L_ITEMLENGTHVALUEn and
L_ITEMLENGTHUNITn
(deprecated)

Length of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMLENGTHVALUE0,
L_PAYMENTREQUEST_n_ITEMLENGTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMLENGTHVALUEn and L_ITEMLENGTHUNITn are deprecated in version
63.0. Use L_PAYMENTREQUEST_0_ITEMLENGTHVALUEm and
L_PAYMENTREQUEST_0_ITEMLENGTHUNITm instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

L_PAYMENTREQUEST_n_ITEM
WIDTHVALUEm,
L_PAYMENTREQUEST_n_ITEM
WIDTHUNITm
L_ITEMWIDTHVALUEn and
L_ITEMWIDTHUNITn
(deprecated)

Width of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMWIDTHVALUE0,
L_PAYMENTREQUEST_n_ITEMWIDTHVALUE1).
Character length and limitations: Any positive integer
L_ITEMWIDTHVALUEn and L_ITEMWIDTHUNITn are deprecated in version
63.0. Use L_PAYMENTREQUEST_n_ITEMWIDTHVALUEm and
L_PAYMENTREQUEST_n_ITEMWIDTHUNITm instead.

L_PAYMENTREQUEST_n_ITEM
HEIGHTVALUEm,
L_PAYMENTREQUEST_n_ITEM
HEIGHTUNITm
L_ITEMHEIGHTVALUEn and
L_ITEMHEIGHTUNITn
(deprecated)

Height of the item. You can pass this data to the shipping carrier as is without
having to make an additional database query. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive, and m specifies the list
item within the payment. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE0,
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUE1).
Character length and limitations: Any positive integer
L_ITEMHEIGHTVALUEn and L_ITEMHEIGHTUNITn are deprecated in version
63.0. Use L_PAYMENTREQUEST_n_ITEMHEIGHTVALUEm and
L_ITEMHEIGHTUNITm instead.

L_PAYMENTREQUEST_n_ITEM
CATEGORYm

Indicates whether the item is digital or physical. For digital goods
(L_PAYMENTREQUEST_n_ITEMCATEGORYm=Digital), this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMCATEGORY0,
L_PAYMENTREQUEST_n_ITEMCATEGORY1). It is one of the following values:
 Digital
 Physical

This field is available since version 65.1.
EbayItemPaymentDetailsItemType Fields
Field

Description

L_PAYMENTREQUEST_n_EB
AYITEMNUMBERm
EBAYITEMNUMBERn
(deprecated)

Auction item number. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive, and m specifies the list item within the payment.
Character length: 765 single-byte characters
EBAYITEMNUMBERn is deprecated since 63.0. Use
L_PAYMENTREQUEST_0_EBAYAUCTIONTXNIDm instead.

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Field

Description

L_PAYMENTREQUEST_n_EB
AYITEMAUCTIONTXNIDm
EBAYITEMAUCTIONTXNIDn
(deprecated)

Auction transaction identification number. You can specify up to 10 payments,
where n is a digit between 0 and 9, inclusive, and m specifies the list item within
the payment.
Character length: 255 single-byte characters
EBAYITEMAUCTIONTXNIDn is deprecated since 63.0. Use
L_PAYMENTREQUEST_0_EBAYAUCTIONTXNIDm instead.

L_PAYMENTREQUEST_n_EB
AYITEMORDERIDm
EBAYITEMORDERIDn
(deprecated)

Auction order identification number. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive, and m specifies the list item within the
payment.
Character length: 64 single-byte characters
EBAYITEMORDERIDn is deprecated since 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMORDERIDm instead.

L_PAYMENTREQUEST_n_EB
AYITEMCARTIDm
EBAYITEMCARTIDn
(deprecated)

The unique identifier provided by eBay for this order from the buyer. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and m
specifies the list item within the payment.
Character length: 255 single-byte characters
EBAYITEMCARTIDn is deprecated since 63.0. Use
L_PAYMENTREQUEST_0_EBAYITEMCARTIDm instead.

User Selected Options Type Fields
Field

Description

SHIPPINGCALCULATIONM
ODE

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

INSURANCEOPTIONSELEC
TED

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

SHIPPINGOPTIONISDEFA
ULT

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

SHIPPINGOPTIONAMOUNT

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

SHIPPINGOPTIONNAME

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

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
GetExpressCheckoutDetails API Operation

Seller Details Type Fields
Field

Description

PAYMENTREQUEST_n_SELLER
PAYPALACCOUNTID

Unique identifier for the merchant. For parallel payments, this field contains
either the Payer Id or the email address of the merchant. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: 127 single-byte alphanumeric characters

Payment Request Info Type Fields
Field

Description

PAYMENTREQUEST_n_TRAN Transaction ID for up to 10 parallel payment requests. You can specify up to 10
SACTIONID
payments, where n is a digit between 0 and 9, inclusive.
This field is available since version 64.0.
PAYMENTREQUEST_n_PAYM Payment request ID. You can specify up to 10 payments, where n is a digit between
ENTREQUESTID
0 and 9, inclusive.
This field is available since version 64.0.
Payment Error Type Fields
Field

Description

PAYMENTREQUEST_n_SH
ORTMESSAGE

xs:string
Payment error short message. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.

PAYMENTREQUEST_n_LO
NGMESSAGE

xs:string
Payment error long message. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.

PAYMENTREQUEST_n_ER
RORCODE

xs:string
Payment error code. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive.

PAYMENTREQUEST_n_SE
VERITYCODE

xs:string
Payment error severity code. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.

PAYMENTREQUEST_n_AC
K

xs:string
Application-specific error values indicating more about the error condition. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
Tax Id Details Type Fields
Field

Description

TAXIDTYPE

TAXIDDETAILS

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

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

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

GIFTMESSAGE

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

GIFTRECEIPTENABLE

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

GIFTWRAPNAME

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

GIFTWRAPAMOUNT

(Optional) Amount only if the buyer selected the gift option on the PayPal pages.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

BUYERMARKETINGEMAIL

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

SURVEYQUESTION

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

SURVEYCHOICESELECTE
D

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

Name-Value Pair API Developer Guide

August 2012

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

The total cost of the transaction to the buyer. If shipping cost (not applicable to
digital goods) and tax charges are known, include them in this value. If not, this
value should be the current sub-total of the order. If the transaction includes
one or more one-time purchases, this field must be equal to the sum of the
purchases. Set this field to 0 if the transaction does not include a one-time
purchase such as when you set up a billing agreement for a recurring payment
that is not immediately charged. When the field is set to 0, purchase-specific
fields are ignored. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive; except for digital goods, which supports single
payments only. For digital goods, the following must be true:
 total cost > 0
 total cost <= total cost passed in the call to SetExpressCheckout
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
AMT is deprecated since version 63.0. Use PAYMENTREQUEST_0_AMT instead.

PAYMENTREQUEST_n_CURRENC
YCODE
CURRENCYCODE (deprecated)

(Optional) A 3-character currency code. Default: USD.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive.
CURRENCYCODE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_CURRENCYCODE instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTREQUEST_n_ITEMAMT
ITEMAMT (deprecated)

PAYMENTREQUEST_n_ITEMAMT is required if you specify
L_PAYMENTREQUEST_n_AMTm.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
ITEMAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ITEMAMT instead.
PAYMENTREQUEST_n_SHIPPIN
GAMT
SHIPPINGAMT (deprecated)

(Optional) Total shipping costs for this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
N O TE :

If you specify a value for PAYMENTREQUEST_n_SHIPPINGAMT, you
must also specify a value for PAYMENTREQUEST_n_ITEMAMT.

Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
SHIPPINGAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGAMT instead.
PAYMENTREQUEST_n_INSURAN
CEAMT
INSURANCEAMT (deprecated)

(Optional) Total shipping insurance costs for this order. The value must be a
non-negative currency amount or null if insurance options are offered. You
can specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Value is a positive number which cannot
exceed $10,000 USD in any currency. It includes no currency symbol. It must
have 2 decimal places, the decimal separator must be a period (.), and the
optional thousands separator must be a comma (,).
INSURANCEAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_INSURANCEAMT instead.

PAYMENTREQUEST_n_SHIPDIS
CAMT
SHIPPINGDISCAMT
(deprecated)

(Optional) Shipping discount for this order, specified as a negative number.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive.
Character length and limitations: Value is a negative number. It includes no
currency symbol. It must have 2 decimal places, the decimal separator must be
a period (.), and the optional thousands separator must be a comma (,).
SHIPPINGDISCAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SHIPPINGDISCAMT instead.

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTREQUEST_n_INSURAN
CEOPTIONOFFERED
INSURANCEOPTIONOFFERED
(deprecated)

(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal Review page. You can specify up to 10 payments, where
n is a digit between 0 and 9, inclusive. Is one of the following values:
 true – The Insurance option displays the string ‘Yes’ and the insurance
amount. If true, the total shipping insurance for this order must be a
positive number.
 false – The Insurance option displays ‘No.’
INSURANCEOPTIONOFFERED is deprecated since version 63.0. Use
PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED instead.

PAYMENTREQUEST_n_HANDLIN
GAMT
HANDLINGAMT (deprecated)

(Optional) Total handling costs for this order. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
N O TE :

If you specify a value for PAYMENTREQUEST_n_HANDLINGAMT, you
must also specify a value for PAYMENTREQUEST_n_ITEMAMT.

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

PAYMENTREQUEST_n_TAXAMT is required if you specify
L_PAYMENTREQUEST_n_TAXAMTm

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

(Optional) Description of items the buyer is purchasing. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive; except for digital
goods, which supports single payments only.
N O TE :

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

Character length and limitations: 127 single-byte alphanumeric characters
DESC is deprecated since version 63.0. Use PAYMENTREQUEST_0_DESC
instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTREQUEST_n_CUSTOM
CUSTOM (deprecated)

(Optional) A free-form field for your own use. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive.
N O TE :

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

Character length and limitations: 256 single-byte alphanumeric characters
CUSTOM is deprecated since version 63.0. Use PAYMENTREQUEST_0_CUSTOM
instead.
PAYMENTREQUEST_n_INVNUM
INVNUM (deprecated)

(Optional) Your own invoice or tracking number.You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital
goods, which supports single payments only.
N O TE :

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

(Optional) Your URL for receiving Instant Payment Notification (IPN) about
this transaction. If you do not specify this value in the request, the notification
URL from your Merchant Profile is used, if one exists.
(Optional) Your URL for receiving Instant Payment Notification (IPN) about
this transaction. If you do not specify this value in the request, the notification
URL from your Merchant Profile is used, if one exists. You can specify up to
10 payments, where n is a digit between 0 and 9, inclusive.
I MP O R TAN T :

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

(Optional) Note to the merchant. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive.
Character length and limitations: 255 single-byte characters
NOTETEXT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_NOTETEXT instead.

PAYMENTREQUEST_n_SOFTDES
CRIPTOR
SOFTDESCRIPTOR (deprecated)

A per transaction description of the payment that is passed to the buyer’s credit
card statement. You can specify up to 10 payments, where n is a digit between
0 and 9, inclusive.
N O TE :

Ignore when PAYMENTREQUEST_n_PAYMENTACTION=Order.

SOFTDESCRIPTOR is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SOFTDESCRIPTOR instead.

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTREQUEST_n_TRANSAC
TIONID
TRANSACTIONID (deprecated)

(Optional) Transaction identification number of the transaction that was
created.You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive.
N O TE :

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

TRANSACTIONID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_TRANSACTIONID instead.
PAYMENTREQUEST_n_ALLOWED
PAYMENTMETHOD
ALLOWEDPAYMENTMETHOD
(deprecated)

(Optional) The payment method type. Specify the value
InstantPaymentOnly. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.
ALLOWEDPAYMENTMETHOD is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ALLOWEDPAYMENTMETHOD instead.

PAYMENTREQUEST_n_PAYMENT
ACTION
PAYMENTACTION (deprecated)

How you want to obtain payment. When implementing parallel payments, this
field is required and must be set to Order. When implementing digital goods,
this field is required and must be set to Sale. You can specify up to 10
payments, where n is a digit between 0 and 9, inclusive; except for digital
goods, which supports single payments only. If the transaction does not include
a one-time purchase, this field is ignored. It is one of the following values:
 Sale – This is a final sale for which you are requesting payment (default).
 Authorization – This payment is a basic authorization subject to
settlement with PayPal Authorization and Capture.
 Order – This payment is an order authorization subject to settlement with
PayPal Authorization and Capture.
N O TE :

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

A unique identifier of the specific payment request. Required when
implementing parallel payments. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive.
Character length and limitations: Up to 127 single-byte characters
PAYMENTREQUESTID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_PAYMENTREQUESTID instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Address Fields
Field

Description

Name-Value Pair API Developer Guide

August 2012

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

L_PAYMENTREQUEST_n_NA
MEm
L_NAMEn (deprecated)

L_PAYMENTREQUEST_n_DE
SCm
L_DESCn (deprecated)

L_PAYMENTREQUEST_n_AM
Tm
L_AMTn (deprecated)

If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must
specify a value for PAYMENTREQUEST_n_ITEMAMT.

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

100

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

L_PAYMENTREQUEST_n_NU
MBERm
L_NUMBERn (deprecated)

L_PAYMENTREQUEST_n_QT
Ym
L_QTYn (deprecated)

L_PAYMENTREQUEST_n_TA
XAMTm
L_TAXAMTn (deprecated)

L_PAYMENTREQUEST_n_IT
EMWEIGHTVALUEm,
L_PAYMENTREQUEST_n_IT
EMWEIGHTUNITm
L_ITEMWEIGHTVALUEn and
L_ITEMWEIGHTUNITn
(deprecated)

Name-Value Pair API Developer Guide

August 2012

101

102

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

L_PAYMENTREQUEST_n_IT
EMLENGTHVALUEm,
L_PAYMENTREQUEST_n_IT
EMLENGTHUNITm
L_ITEMLENGTHVALUEn and
L_ITEMLENGHTUNITn
(deprecated)

L_PAYMENTREQUEST_n_IT
EMWIDTHVALUEm,
L_PAYMENTREQUEST_n_IT
EMWIDTHUNITm
L_ITEMWIDTHVALUEn and
L_ITEMWIDTHUNITn
(deprecated)

L_PAYMENTREQUEST_n_IT
EMHEIGHTVALUEm,
L_PAYMENTREQUEST_n_IT
EMHEIGHTUNITm
L_ITEMHEIGHTVALUEn and
L_ITEMHEIGHTUNITn
(deprecated)

L_PAYMENTREQUEST_n_IT
EMURLm
L_ITEMURLn (deprecated)

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

L_PAYMENTREQUEST_n_IT
EMCATEGORYm

This field is available since version 65.1.
EbayItemPaymentDetailsItemType Fields
Field

Description

L_PAYMENTREQUEST_n_EB
AYITEMNUMBERm
L_EBAYITEMNUMBERn
(deprecated)

L_PAYMENTREQUESST_n_E
BAYITEMAUCTIONTXNIDm
L_EBAYITEMAUCTIONTXNI
Dn (deprecated)

L_PAYMENTREQUEST_n_EB
AYITEMORDERIDm
L_EBAYITEMORDERIDn
(deprecated)

Name-Value Pair API Developer Guide

August 2012

103

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

L_PAYMENTREQUEST_n_EB
AYCARTIDm
L_EBAYITEMCARTIDn
(deprecated)

UserSelectedOptions Fields
Field

Description

INSURANCEOPTIONSELEC
TED

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

SHIPPINGOPTIONISDEFA
ULT

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

SHIPPINGOPTIONAMOUNT

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

SHIPPINGOPTIONNAME

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

Seller Details Type Fields

104

Field

Description

PAYMENTREQUEST_n_SELL
ERID
SELLERID (deprecated)

(Optional) Unique non-changing identifier for the merchant at the marketplace
site. This ID is not displayed. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive.
Character length and limitations: 13 single-byte alphanumeric characters
SELLERID is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SELLERID instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTREQUEST_n_SELL
ERUSERNAME
SELLERUSERNAME
(deprecated)

xs:string
(Optional) Current name of the merchant or business at the marketplace site. This
name may be shown to the buyer. You can specify up to 10 payments, where n is a
digit between 0 and 9, inclusive.
SELLERUSERNAME is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SELLERUSERNAME instead.

PAYMENTREQUEST_n_SELL
ERREGISTRATIONDATE
SELLERREGISTRATIONDAT
E (deprecated)

(Optional) Date when the merchant registered with the marketplace. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z
SELLERREGISTRATIONDATE is deprecated since version 63.0. Use
PAYMENTREQUEST_0_SELLERREGISTRATIONDATE instead.

DoExpressCheckoutPayment Response Message

DoExpressCheckoutPayment 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

PAYMENTTYPE

Information about the payment.

NOTE

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

REDIRECTREQUIRED

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

Name-Value Pair API Developer Guide

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

August 2012

105

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

SUCCESSPAGEREDIRECT
REQUESTED

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

BILLINGAGREEMENTID

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

L_FMFfilterIDn
(deprecated)

Filter ID, including the filter type, (PENDING, REPORT, or DENY), the filter ID, and
the entry number, n, starting from 0. Filter ID is one of the following values:
 1 - AVS No Match
 2 - AVS Partial Match
 3 - AVS Unavailable/Unsupported
 4 - Card Security Code (CSC) Mismatch
 5 - Maximum Transaction Amount
 6 - Unconfirmed Address
 7 - Country Monitor
 8 - Large Order Number
 9 - Billing/Shipping Address Mismatch
 10 - Risky ZIP Code
 11 - Suspected Freight Forwarder Check
 12 - Total Purchase Price Minimum
 13 - IP Address Velocity
 14 - Risky Email Address Domain Check
 15 - Risky Bank Identification Number (BIN) Check
 16 - Risky IP Address Range
 17 - PayPal Fraud Model
This field is deprecated since version 63.0. Use L_PAYMENTINFO_0_FMFfilterIDn
instead.

106

L_FMFfilterNAMEn
(deprecated)

Filter name, including the filter type, (PENDING, REPORT, or DENY), the filter
NAME, and the entry number, n, starting from 0.
This field is deprecated since version 63.0. Use L_PAYMENTINFO_0_FMFfilterNAMEn
instead.

PAYMENTINFO_n_SHIPP
INGAMT
SHIPPINGAMT
(deprecated)

Amount of shipping charged on this transaction.
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Regardless of currency, decimal separator must be a period (.), and
the optional thousands separator must be a comma (,). Equivalent to nine characters
maximum for USD.
If you specify a value for PAYMENTINFO_n_SHIPPINGAMT, you must also specify a
value for PAYMENTINFO_n_ITEMAMT.
SHIPPINGAMT is deprecated since version 63.0. Use
PAYMENTINFO_n_SHIPPINGAMT instead.

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTINFO_n_SELLE
RID

Unique, non-changing identifier for the merchant at the marketplace site. (Optional)
You can specify up to 10 payments, where ‘n’ is a digit between 0 and 9, inclusive.
Character length and limitations: 13 single-byte alphanumeric characters.

PAYMENTINFO_n_SELLE
RUSERNAME

Current name of the merchant or business at the marketplace site. This name may be
shown to the buyer.
You can specify up to 10 payments, where ‘n’ is a digit between 0 and 9, inclusive.

PAYMENTINFO_n_SELLE
RREGISTRATIONDATE

Date when the merchant registered with the marketplace.
You can specify up to 10 payments, where ‘n’ is a digit between 0 and 9, inclusive.
Character length and limitations: Date and time are in UTC/GMT format. For
example: 2011-06-24T05:38:?48Z.

PAYMENTINFO_n_PAREN
TTRANSACTIONID
PARENTTRANSACTIONID
(deprecated)

Parent or related transaction identification number. This field is populated for the
following transaction types:
 Reversal
 Capture of an authorized transaction
 Reauthorization of a transaction
 Capture of an order. The value of ParentTransactionID is the original
OrderID.
 Authorization of an order. The value of ParentTransactionID is the original
OrderID.
 Capture of an order authorization
 Void of an order. The value of ParentTransactionID is the original OrderID.

Character length and limits: 19 single-byte characters maximum.
PARENTTRANSACTIONID is deprecated since version 63.0. Use
PAYMENTINFO_n_PARENTTRANSACTIONID instead.
PAYMENTINFO_n_RECEI
PTID
RECEIPTID
(deprecated)

Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format.
RECEIPTID is deprecated since version 63.0. Use PAYMENTINFO_n_RECEIPTID
instead.

PAYMENTINFO_n_EXPEC
TEDECHECKCLEARDATE
EXPECTEDECHECKCLEAR
DATE
(deprecated)

eCheck latest expected clear date.
EXPECTEDECHECKCLEARDATE is deprecated since version 63.0. Use
PAYMENTINFO_n_EXPECTEDECHECKCLEARDATE instead.

PAYMENTINFO_n_SHIPP
INGMETHOD
SHIPPINGMETHOD
(deprecated)

Shipping method selected by the user during check-out.
SHIPPINGMETHOD is deprecated since version 63.0. Use
PAYMENTINFO_n_SHIPPINGMETHOD instead.

PAYMENTINFO_n_INSTR
UMENTCATEGORY

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

PAYMENTINFO_n_OFFER
CODE

Code used to identify the promotion offer.

Name-Value Pair API Developer Guide

August 2012

107

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTINFO_n_OFFER
TRACKINGID

Unique identification for merchant/buyer/offer combo.

Payment Information Fields

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

Description

PAYMENTINFO_n_TRANS
ACTIONID
TRANSACTIONID
(deprecated)

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

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

Character length and limitations: 19 single-byte characters
TRANSACTIONID is deprecated since version 63.0. Use
PAYMENTINFO_n_TRANSACTIONID instead.
PAYMENTINFO_n_TRANS
ACTIONTYPE
TRANSACTIONTYPE
(deprecated)

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

PAYMENTINFO_n_PAYME
NTTYPE
PAYMENTTYPE
(deprecated)

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

108

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTINFO_n_ORDER
TIME
ORDERTIME (deprecated)

Time/date stamp of payment.
Character length and limitations: Date and time are in UTC/GMTformat, for
example, 2011-06-24T05:38:48Z
ORDERTIME is deprecated since version 63.0. Use PAYMENTINFO_0_ORDERTIME
instead.

PAYMENTINFO_n_AMT
AMT (deprecated)

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

PAYMENTINFO_n_CURRE
NCYCODE
CURRENCYCODE
(deprecated)

A 3-character currency code. Default: USD.
CURRENCYCODE is deprecated since version 63.0. Use
PAYMENTINFO_0_CURRENCYCODE instead.

PAYMENTINFO_n_FEEAM
T
FEEAMT (deprecated)

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

PAYMENTINFO_n_SETTL
EAMT
SETTLEAMT (deprecated)

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

PAYMENTINFO_n_TAXAM
T
TAXAMT (deprecated)

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

Name-Value Pair API Developer Guide

August 2012

109

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTINFO_n_EXCHA
NGERATE
EXCHANGERATE
(deprecated)

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

PAYMENTINFO_n_PAYME
NTSTATUS
PAYMENTSTATUS
(deprecated)

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

110

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTINFO_n_PENDI
NGREASON
PENDINGREASON
(deprecated)

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

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

PENDINGREASON is deprecated since version 63.0. Use
PAYMENTINFO_0_PENDINGREASON instead.

Name-Value Pair API Developer Guide

August 2012

111

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTINFO_n_REASO
NCODE
REASONCODE
(deprecated)

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

PAYMENTINFO_n_HOLDD
ECISION

xs:string
Reason that this payment is being held. It is one of the following values:
Reason that this payment is being held. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive. It is one of the following values:
 newsellerpaymenthold – This is a new merchant.
 paymenthold – A hold is placed on the merchant’s transaction for a reason not
listed.
This field is available since version 71.0 and is returned only if PaymentStatus is
Completed-Funds-Held.
This field is available since version 71.0 and is returned only if
PAYMENTINFO_n_PAYMENTSTATUS is Completed-Funds-Held.

PAYMENTINFO_n_PROTE
CTIONELIGIBILITY
PROTECTIONELIGIBILI
TY (deprecated)

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

112

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

PAYMENTINFO_n_PROTE
CTIONELIGIBILITYTYP
E

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

This field is available since version 64.4.
STOREID

StoreId as entered in the transaction

TERMINALID

TerminalId as entered in the transaction

PAYMENTINFO_n_EBAYI
TEMAUCTIONTXNID
EBAYITEMAUCTIONTXNI
D (deprecated)

eBay transaction identification number.
eBay transaction identification number. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive.
Character length and limitations: 255 single-byte characters
EBAYITEMAUCTIONTXNID is deprecated since version 63.0. Use
PAYMENTINFO_0_EBAYITEMAUCTIONTXNID instead.

PAYMENTREQUEST_n_PA
YMENTREQUESTID
PAYMENTREQUESTID
(deprecated)

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

Name-Value Pair API Developer Guide

August 2012

113

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Field

Description

L_PAYMENTINFO_n_FMF

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

filterIDm

L_FMFfilterIDn
(deprecated)

You can specify up to 10 payments, where n is a digit between 0 and 9, inclusive, and
m specifies the list item within the payment.
L_FMFfilterIDn is deprecated since version 63.0. Use
L_PAYMENTINFO_n_FMFfilterIDn instead.
L_PAYMENTINFO_n_FMF
filterNAMEm

L_FMFfilterNAMEn
(deprecated)

114

Filter name, including the filter type, (PENDING, REPORT, or DENY), the filter NAME,
and the entry number, m, starting from 0.
Filter name, including the filter type, (PENDING, REPORT, or DENY), the filter NAME,
and the entry number, m, starting from 0. You can specify up to 10 payments, where n
is a digit between 0 and 9, inclusive, and m specifies the list item within the payment.
L_FMFfilterNAMEn is deprecated since version 63.0. Use
L_PAYMENTINFO_n_FMFfilterNAMEn instead.

InstrumentDetails

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

OfferDetails

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

August 2012

Name-Value Pair API Developer Guide

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation

Payment Error Type Fields
Field

Description

PAYMENTREQUEST_n_SH
ORTMESSAGE

xs:string
Payment error short message. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.

PAYMENTREQUEST_n_LO
NGMESSAGE

xs:string
Payment error long message. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.

PAYMENTREQUEST_n_ER
RORCODE

xs:string
Payment error code. You can specify up to 10 payments, where n is a digit between 0
and 9, inclusive.

PAYMENTREQUEST_n_SE
VERITYCODE

xs:string
Payment error severity code. You can specify up to 10 payments, where n is a digit
between 0 and 9, inclusive.

PAYMENTREQUEST_n_AC
K

xs:string
Application-specific error values indicating more about the error condition. You can
specify up to 10 payments, where n is a digit between 0 and 9, inclusive.

UserSelectedOptions Fields
Field

Description

SHIPPINGCALCULATIONM
ODE

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

INSURANCEOPTIONSELEC
TED

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

SHIPPINGOPTIONISDEFA
ULT

SHIPPINGOPTIONAMOUNT

SHIPPINGOPTIONNAME

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

Name-Value Pair API Developer Guide

August 2012

115

ExpressCheckout API Operations
DoExpressCheckoutPayment API Operation
Seller Details Type Fields

116

Field

Description

PAYMENTREQUEST_n_SELLER
PAYPALACCOUNTID

PAYMENTREQUEST_n_SECURE
MERCHANTACCOUNTID

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

August 2012

Name-Value Pair API Developer Guide

GetBalance API Operation

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

GetBalance Request Message

GetBalance Request Fields
Field

Description

METHOD

(Required) Must be GetBalance.

RETURNALLCURRENCIES

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

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

GetBalance Response Message

GetBalance Response Fields
Field

Description

L_AMTn

Available balance and associated currency code for the primary currency holding.

L_CURRENCYCODEn

Currency code, such as USD, associated with the holding.

Name-Value Pair API Developer Guide

August 2012

117

118

GetBalance API Operation
GetBalance Response Message

August 2012

Name-Value Pair API Developer Guide

GetPalDetails API Operation

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

GetPalDetails Request Message

GetPalDetails Request Fields
Field

Description

METHOD

(Required) Must be GetPalDetails.

GetPalDetails Response Message

GetPalDetails Response Fields
Field

Description

PAL

PayPal-assigned merchant account number.

Name-Value Pair API Developer Guide

August 2012

119

GetPalDetails API Operation
GetPalDetails Response Message

Field

Description

LOCALE

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

120

August 2012

Name-Value Pair API Developer Guide

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

GetTransactionDetails Request Message

GetTransactionDetails Request Fields
Field

Description

METHOD

Must be GetTransactionDetails.

TRANSACTIONID

(Required) Unique identifier of a transaction.
NOTE:

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

Character length and limitations: 17 single-byte alphanumeric characters

GetTransactionDetails Response Message
NOT E :

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

GetTransactionDetails Response Fields
Field

Description

SHIPPINGCALCULATION
MODE

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

Name-Value Pair API Developer Guide

August 2012

121

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

INSURANCEOPTIONSELE
CTED

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

L_SHIPPINGOPTIONISD
EFAULTn

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

122

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

L_SHIPPINGOPTIONNAM
En

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

L_SHIPPINGOPTIONAMO
UNTn

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

GIFTMESSAGE

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

GIFTRECEIPTENABLE

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

GIFTWRAPNAME

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

GIFTWRAPAMOUNT

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

BUYERMARKETINGEMAIL

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

SURVEYQUESTION

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

August 2012

Name-Value Pair API Developer Guide

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

SURVEYCHOICESELECTE
D

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

Receiver Information Fields
Field

Description

RECEIVERBUSINESS

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

RECEIVEREMAIL

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

RECEIVERID

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

Payer Information Fields
Field

Description

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

PAYERID

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

PAYERSTATUS

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

COUNTRYCODE

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

PAYERBUSINESS

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

Name-Value Pair API Developer Guide

August 2012

123

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Payer Name Fields
Field

Description

SALUTATION

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

FIRSTNAME

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

MIDDLENAME

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

LASTNAME

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

SUFFIX

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

Address Fields

124

Field

Description

ADDRESSOWNER

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

ADDRESSSTATUS

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

SHIPTONAME

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

SHIPTOSTREET

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

SHIPTOSTREET2

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

SHIPTOCITY

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

SHIPTOSTATE

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

SHIPTOZIP

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

August 2012

Name-Value Pair API Developer Guide

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

SHIPTOCOUNTRYCODE

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

SHIPTOPHONENUM

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

Payment Information Fields
Field

Description

TRANSACTIONID

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

PARENTTRANSACTIONID

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

RECEIPTID

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

TRANSACTIONTYPE

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

PAYMENTTYPE

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

ORDERTIME

Name-Value Pair API Developer Guide

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

August 2012

125

126

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

AMT

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

CURRENCYCODE

A 3-character currency code.

FEEAMT

SETTLEAMT

TAXAMT

EXCHANGERATE

Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency. If the buyer chooses to pay with a currency other than the
non-primary currency, the conversion occurs in the buyer’s account.
Character length and limitations: Decimal value that does not exceed 17 characters,
including decimal point

August 2012

Name-Value Pair API Developer Guide

GetTransactionDetails API Operation
GetTransactionDetails Response Message

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

Name-Value Pair API Developer Guide

August 2012

127

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

PENDINGREASON

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

REASONCODE

128

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

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

August 2012

Name-Value Pair API Developer Guide

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

PROTECTIONELIGIBILI
TY

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

PROTECTIONELIGIBILI
TYTYPE

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

This field is introduced in API version 64.4.
STOREID

xs:string
StoreId as entered in the transaction.

TERMINALID

xs:string
TerminalId as entered in the transaction.

Payment Item Information Fields
Field

Description

INVNUM

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

CUSTOM

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

NOTE

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

SALESTAX

Amount of tax charged on payment.

Name-Value Pair API Developer Guide

August 2012

129

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Payment Item Fields
Field

Description

EbayItemTxnId
L_EBAYITEMTXNID

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

L_DESCn

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

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

These parameters must be ordered sequentially beginning with 0 (for example
L_DESC0, L_DESC1).

130

L_NUMBERn

Item number set by you. If this was a shopping cart transaction, PayPal appends the
number of the item to the HTML item_number variable, for example,
item_number1, item_number2, and so forth.
Character length and limitations: 127 single-byte alphanumeric characters
These parameters must be ordered sequentially beginning with 0 (for example
L_NUMBER0, L_NUMBER1).

L_QTYn

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

CouponID
L_COUPONIDn

xs:string
(Optional) Coupon identification number.

CouponAmount
L_COUPONAMOUNTn

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

CouponAmountCurrenc
y
L_COUPONAMOUNTCURRE
NCYn

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

LoyaltyCardDiscount
Amount
L_LOYALTYCARDDISCOU
NTAMOUNTn

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

LoyaltyCardDiscount
Currency
L_LOYALTYCARDISCOUN
TCURRENCYn

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

L_AMTn

Cost of item.
These parameters must be ordered sequentially beginning with 0 (for example
L_AMT0, L_AMT1).

NOTE:

Use character string as shown.

August 2012

Name-Value Pair API Developer Guide

GetTransactionDetails API Operation
GetTransactionDetails Response Message

Field

Description

L_OPTIONSNAMEn

PayPal option names for an item in the shopping cart; each name corresponds to an
option value. There can be multiple option names per item.
The option names are ordered sequentially beginning with 0 (for example,
L_OPTIONSNAMES0, L_OPTIONSNAME1).

L_OPTIONSVALUEn

PayPal option values corresponding to option names of an item in the shopping cart.
The option names are ordered sequentially beginning with 0 (for example,
L_OPTIONSVALUE0, L_OPTIONSVALUE1).

Auction Information Fields
Field

Description

BUYERID

Buyer’s auction ID.

CLOSINGDATE

Auction’s close date.

MULTIITEM

Counter used for multi-item auction payments.

Subscription Terms Fields
Field

Description

AMOUNT

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

PERIOD

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

Name-Value Pair API Developer Guide

August 2012

131

132

GetTransactionDetails API Operation
GetTransactionDetails Response Message

August 2012

Name-Value Pair API Developer Guide

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

ManagePendingTransactionStatus Request Message

ManagePendingTransactionStatus Request Fields
Field

Description

METHOD

(Required) Must be ManagePendingTransactionStatus.

TRANSACTIONID

(Required) The transaction ID of the payment transaction.

ACTION

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

Name-Value Pair API Developer Guide

August 2012

133

ManagePendingTransactionStatus API Operation
ManagePendingTransactionStatus Response Message

M a n a g e P e n d i n g Tr a n s a c t i o n Sta t u s R e s p o n s e M e s s a g e

ManagePendingTransactionStatus Response Fields

134

Field

Description

TRANSACTIONID

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

STATUS

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

August 2012

Name-Value Pair API Developer Guide

MassPay API Operation

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

MassPay Request Message

MassPay Request Fields
Field

Description

METHOD

(Required) Must be MassPay.

EMAILSUBJECT

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

CURRENCYCODE

Currency code.
Character length and limitations: 3 single-byte characters

RECEIVERTYPE

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

MassPay Response Message

MassPay Response Fields
The fields in the response are the standard response header fields.

Name-Value Pair API Developer Guide

August 2012

135

136

MassPay API Operation
MassPay Response Message

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and
Reference Transactions API
Operations

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

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

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

CreateRecurringPaymentsProfile Request Message
CreateRecurringPaymentsProfile Request Fields
Field

Description

METHOD

(Required) Must be CreateRecurringPaymentsProfile.

TOKEN

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

Name-Value Pair API Developer Guide

Tokens expire after approximately 3 hours.

August 2012

137

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation
Recurring Payments Profile Details Fields
Field

Description

SUBSCRIBERNAME

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

PROFILESTARTDATE

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

The profile may take up to 24 hours for activation.

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

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

Schedule Details Fields
Field

Description

DESC

(Required) Description of the recurring payment.
NOTE:

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

Character length and limitations: 127 single-byte alphanumeric characters

138

MAXFAILEDPAYMENTS

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

AUTOBILLOUTAMT

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

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Billing Period Details Fields
Field

Description

BILLINGPERIOD

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

BILLINGFREQUENCY

The combination of BillingPeriod and BillingFrequency cannot
exceed one year.

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

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

TOTALBILLINGCYCLES

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

AMT

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

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

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

Name-Value Pair API Developer Guide

The combination of BillingPeriod and BillingFrequency cannot
exceed one year.

August 2012

139

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Field

Description

TRIALBILLINGFREQUEN
CY

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

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

TRIALTOTALBILLINGCY
CLES

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

TRIALAMT

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

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

(Required) Currency code (default is USD).
Character length and limitations: 3 single-byte characters

SHIPPINGAMT

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

All amounts in the request must have the same currency.

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

All amounts in the request must have the same currency.

140

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Actvation Details Fields
Field

Description

INITAMT

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

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

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

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

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

Name-Value Pair API Developer Guide

August 2012

141

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Field

Description

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

Credit Card Details Fields
Field

Description

CREDITCARDTYPE

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

142

ACCT

EXPDATE

CVV2

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

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Payer Information Fields
Field

Description

(Required) Email address of buyer.
Character length and limitations: 127 single-byte characters

PAYERID

(Optional) Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters

PAYERSTATUS

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

COUNTRYCODE

(Optional) Buyer’s country of residence in the form of ISO standard 3166 twocharacter country codes.
Character length and limitations: 2 single-byte characters

BUSINESS

(Optional) Buyer’s business name.
Character length and limitations: 127 single-byte characters
Payer Name 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
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

Name-Value Pair API Developer Guide

August 2012

143

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Field

Description

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

Payment Details Item Fields
Field

Description

L_PAYMENTREQUEST_n_IT
EMCATEGORYm

Indicates whether the item is digital or physical. For digital goods, this field is
required and must be set to Digital to get the best rates. Is one of the following
values. These parameters must be ordered sequentially beginning with 0 (for
example L_PAYMENTREQUEST_n_ITEMCATEGORY0,
L_PAYMENTREQUEST_n_ITEMCATEGORY1). Is one of the following values:
 Digital
 Physical
This field is introduced in version 69.0.

144

L_PAYMENTREQUEST_n_NA
MEm

Item name. This field is required when ItemCategory is passed.
Item name. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.

L_PAYMENTREQUEST_n_DE
SCm

(Optional) Item description. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_DESC0,
L_PAYMENTREQUEST_n_DESC1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
CreateRecurringPaymentsProfile API Operation

Field

Description

L_PAYMENTREQUEST_n_AM
Tm

Cost of item. This field is required when ItemCategory is passed.
Cost of item. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 69.0.

L_PAYMENTREQUEST_n_NU
MBERm

(Optional) Item number. These parameters must be ordered sequentially beginning
with 0 (for example L_PAYMENTREQUEST_n_NUMBER0,
L_PAYMENTREQUEST_n_NUMBER1).
Character length and limitations: 127 single-byte characters
This field is introduced in version 69.0.

L_PAYMENTREQUEST_n_QT
Ym

Item quantity. This field is required when ItemCategory is passed.
Item quantity. This field is required when
L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. These parameters must be
ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).
Character length and limitations: Any positive integer
This field is introduced in version 69.0.

L_PAYMENTREQUEST_n_TA
XAMTm

(Optional) Item sales tax. These parameters must be ordered sequentially
beginning with 0 (for example L_PAYMENTREQUEST_n_TAXAMT0,
L_PAYMENTREQUEST_n_TAXAMT1).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 69.0.

CreateRecurringPaymentsProfile Response Message
CreateRecurringPaymentsProfile Response Fields
Field

Description

PROFILEID

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

Name-Value Pair API Developer Guide

August 2012

145

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Field

Description

PROFILESTATUS

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

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

GetRecurringPaymentsProfileDetails Request Message

GetRecurringPaymentsProfileDetails Request Fields
Field

Description

METHOD

(Required) Must be GetRecurringPaymentsProfileDetails.

PROFILEID

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

GetRecurringPaymentsProfileDetails Response Message

GetRecurringPaymentsProfileDetails Response Fields

146

Field

Description

PROFILEID

Recurring payments profile ID returned in the
CreateRecurringPaymentsProfile response.

STATUS

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

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Field

Description

DESC

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

AUTOBILLOUTAMT

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

MAXFAILEDPAYMENTS

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

AGGREGATEAMOUNT

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

AGGREGATEOPTIONALAM
OUNT

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

FINALPAYMENTDUEDATE

Final scheduled payment due date before the profile expires.

Recurring Payments Profile Details Fields
Field

Description

SUBSCRIBERNAME

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

PROFILESTARTDATE

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

PROFILEREFERENCE

Name-Value Pair API Developer Guide

The profile may take up to 24 hours for activation.

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

August 2012

147

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
Ship To AddressType Fields
Field

Description

ADDRESSSTATUS

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

SHIPTONAME

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

SHIPTOSTREET

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

SHIPTOSTREET2

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

SHIPTOCITY

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

SHIPTOSTATE

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

SHIPTOZIP

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

SHIPTOCOUNTRYCODE

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

Billing Period Details Fields
Field

Description

BILLINGPERIOD

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

148

The combination of BillingPeriod and BillingFrequency cannot
exceed one year.

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Field

Description

REGULARBILLINGPERIO
D

Unit for billing during this regular subscription period. It is one of the following
values:
 Day
 Week
 SemiMonth
 Month
 Year

For SemiMonth, billing is done on the 1st and 15th of each month.
NOTE:

The combination of RegularBillingPeriod and
RegularBillingFrequency cannot exceed one year.

This field is available since version 53.0.
BILLINGFREQUENCY

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

REGULARBILLINGFREQU
ENCY

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

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

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

This field is available since version 53.0.
TOTALBILLINGCYCLES

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

REGULARTOTALBILLING
CYCLES

Number of billing cycles for the regular payment period.
 For the regular payment period, if no value is specified or the value is 0, the
regular payment period continues until the profile is canceled or deactivated.
 For the regular payment period, if the value is greater than 0, the regular payment
period will expire after the trial period is finished and continue at the billing
frequency for RegularTotalBillingCycles cycles.
This field is available since version 53.0.

Name-Value Pair API Developer Guide

August 2012

149

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Field

Description

AMT

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

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

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

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

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

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

All amounts in the request must have the same currency.

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

All amounts in the request must have the same currency.

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

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

All amounts in the request must have the same currency.

150

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Field

Description

REGULARTAXAMT

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

All amounts in the request must have the same currency.

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

(Required) Currency code (default is USD).
Character length and limitations: 3 single-byte characters

REGULARCURRENCYCODE

(Required) Currency code (default is USD).
This field is available since version 53.0.

Recurring Payments Summary Details Fields
Field

Description

NEXTBILLINGDATE

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

NUMCYCYLESCOMPLETED

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

NUMCYCLESREMAINING

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

OUTSTANDINGBALANCE

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

FAILEDPAYMENTCOUNT

The total number of failed billing cycles for this profile.

LASTPAYMENTDATE

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

LASTPAYMENTAMT

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

Name-Value Pair API Developer Guide

August 2012

151

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation
Credit Card Details Fields
Field

Description

CREDITCARDTYPE

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

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

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

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

EXPDATE

STARTDATE

Month and year that Maestro card was issued.
Character length and limitations: Must be 6 digits, including leading zero, in the
format MMYYYY

ISSUENUMBER

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

Payer Info Fields

152

Field

Description

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

FIRSTNAME

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

LASTNAME

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

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
GetRecurringPaymentsProfileDetails API Operation

Address Fields
Field

Description

ADDRESSOWNER

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

ADDRESSSTATUS

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

SHIPTONAME

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

SHIPTOSTREET

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

SHIPTOSTREET2

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

SHIPTOCITY

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

SHIPTOSTATE

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

SHIPTOZIP

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

SHIPTOCOUNTRYCODE

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

SHIPTOPHONENUM

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

Name-Value Pair API Developer Guide

August 2012

153

Recurring Payments and Reference Transactions API Operations
ManageRecurringPaymentsProfileStatus API Operation

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

ManageRecurringPaymentsProfileStatus Request Message
ManageRecurringPaymentsProfileStatus Request Fields
Field

Description

METHOD

(Required) Must be ManageRecurringPaymentsProfileStatus.

PROFILEID

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

ACTION

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

NOTE

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

ManageRecurringPaymentsProfileStatus Response Message

ManageRecurringPaymentsProfileStatus Response Fields

154

Field

Description

PROFILEID

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

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
BillOutstandingAmount API Operation

BillOutstandingAmount API Operation
The BillOutstandingAmount API operation bills the buyer for the outstanding balance
associated with a recurring payments profile.

BillOutstandingAmount Request Message

BillOutstandingAmount Request Fields
Field

Description

METHOD

(Required) Must be BillOutstandingAmount.

PROFILEID

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

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

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

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

NOTE

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

BillOutstandingAmount Response Message

BillOutstandingAmount Response Fields
Field

Description

PROFILEID

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

Name-Value Pair API Developer Guide

August 2012

155

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

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

UpdateRecurringPaymentsProfile Request Message

UpdateRecurringPaymentsProfile Request Fields
Field

Description

METHOD

(Required) Must be UpdateRecurringPaymentsProfile.

PROFILEID

NOTE

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

DESC

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

SUBSCRIBERNAME

PROFILEREFERENCE

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

ADDITIONALBILLINGCY
CLES

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

AMT

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

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

156

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

Field

Description

SHIPPINGAMT

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

All amounts in the request must have the same currency.

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

TAXAMT

NOTE:

All amounts in the request must have the same currency.

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

AUTOBILLOUTAMT

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

MAXFAILEDPAYMENTS

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

PROFILESTARTDATE

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

The profile may take up to 24 hours for activation.

Character length and limitations: Must be a valid date, in UTC/GMT format
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

Name-Value Pair API Developer Guide

August 2012

157

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

Field

Description

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

Billing Period Details Fields
Field

Description

TOTALBILLINGCYCLES

AMT

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

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

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

158

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

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

Field

Description

TRIALAMT

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

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

(Required) Currency code (default is USD).
Character length and limitations: 3 single-byte characters

SHIPPINGAMT

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

All amounts in the request must have the same currency.

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

TAXAMT

NOTE:

All amounts in the request must have the same currency.

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

Description

CREDITCARDTYPE

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

Name-Value Pair API Developer Guide

August 2012

159

Recurring Payments and Reference Transactions API Operations
UpdateRecurringPaymentsProfile API Operation

Field

Description

ACCT

EXPDATE

CVV2

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

(Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters

FIRSTNAME

(Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters

LASTNAME

(Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Address Fields

160

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

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
CreateBillingAgreement API Operation

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

UpdateRecurringPaymentsProfile Response Message

UpdateRecurringPaymentsProfile Response Fields
Field

Description

PROFILEID

CreateBillingAgreement API Operation
The CreateBillingAgreement API operation creates a billing agreement with a PayPal
account holder. CreateBillingAgreement is only valid for reference transactions.

CreateBillingAgreement Request Message

CreateBillingAgreement Request Fields
Field

Description

METHOD

(Required) Must be CreateBillingAgreement.

TOKEN

(Required) The time-stamped token returned in the
SetCustomerBillingAgreement response.
NOTE:

The token expires after 3 hours.

Character length and limitations: 20 single-byte characters

Name-Value Pair API Developer Guide

August 2012

161

Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation

CreateBillingAgreement API Response Message

CreateBillingAgreement Response Fields
Field

Description

BILLINGAGREEMENTID

Identification number of the billing agreement.

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

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

SetCustomerBillingAgreement Request Message

SetCustomerBillingAgreement Request Fields
Field

Description

METHOD

(Required) Must be SetCustomerBillingAgreement.

RETURNURL

(Required) URL to which the buyer’s browser is returned after choosing to pay with
PayPal.
NOTE:

PayPal recommends that the value be the final review page on which the
buyer confirms the billing agreement.

Character length and limitations: no limit
CANCELURL

(Required) URL to which the customer is returned if he does not approve the use of
PayPal to pay you.
NOTE:

PayPal recommends that the value be the original page on which the
customer chose to pay with PayPal or establish a billing agreement.

Character length and limitations: no limit

162

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation

Field

Description

LOCALECODE

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

Any other value defaults to US.
Character length and limitations: 2 single-byte characters
PAGESTYLE

Name-Value Pair API Developer Guide

(Optional) Sets the Custom Payment Page Style for payment pages associated with
this button/link. This value corresponds to the HTML variable page_style for
customizing payment pages. The value is the same as the Page Style Name you chose
when adding or editing the page style in your PayPal account.
Character length and limitations: 30 single-byte alphabetic characters

August 2012

163

Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation

Field

Description

HDRIMG

(Optional) A URL for the image you want to appear at the top left of the payment
page. The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal
recommends that you provide an image that is stored on a secure (https) server.
Character length and limitations: 127 single-byte alphanumeric characters

HDRBORDERCOLOR

(Optional) Sets the border color around the header of the payment page. The border is
a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels
high.
Character length and limitations: 6-character HTML hexadecimal color code in
ASCII

HDRBACKCOLOR

(Optional) Sets the background color for the header of the payment page. By default,
the color is white.
Character length and limitation: 6-character HTML hexadecimal color code in ASCII

PAYFLOWCOLOR

(Optional) Sets the background color for the payment page.
Character length and limitation: 6-character HTML hexadecimal color code in ASCII

(Optional) Email address of the buyer as entered during checkout. PayPal uses this
value to pre-fill the PayPal membership sign-up portion of the PayPal login page.
Character length and limit: 127 single-byte alphanumeric characters
BillingAgreementDetails Fields

164

Field

Description

L_BILLINGTYPEn

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
SetCustomerBillingAgreement API Operation

Field

Description

BILLINGTYPE

Other defined values are not valid.
L_BILLINGAGREEMENTD
ESCRIPTIONn

L_PAYMENTTYPEn

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

L_BILLINGAGREEMENTC
USTOMn

For recurring payments, this field is ignored.

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

For recurring payments, this field is ignored.

Character length and limitations: 256 single-byte alphanumeric bytes

SetCustomerBillingAgreement Response Message

SetCustomerBillingAgreement Response Fields
Field

Description

TOKEN

A unique time-stamped token, which uniquely identifies this transaction in
subsequent API calls.
N O TE :

The token expires after 3 hours.

Character length and limitations: 20 single-byte characters

Name-Value Pair API Developer Guide

August 2012

165

Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation

GetBillingAgreementCustomerDetails API Operation
The GetBillingAgreementCustomerDetails API operation obtains information about a billing
agreement’s PayPal account holder.

GetBillingAgreementCustomerDetails Request Message

GetBillingAgreementCustomerDetails Request Fields
Field

Description

METHOD

(Required) Must be GetBillingAgreementCustomerDetails.

TOKEN

(Required) The time-stamped token returned in the
SetCustomerBillingAgreement response.
NOTE:

The token expires after 3 hours.

Character length and limitations: 20 single-byte characters

GetBillingAgreementCustomerDetails Response Message

Payer Information Fields
Field

Description

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

166

COUNTRYCODE

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

PAYERBUSINESS

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

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
GetBillingAgreementCustomerDetails API Operation

PayerNameType Fields
Field

Description

SALUTATION

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

FIRSTNAME

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

MIDDLENAME

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

LASTNAME

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

SUFFIX

Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Address Fields

Field

Description

ADDRESSSTATUS

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

SHIPTONAME

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

SHIPTOSTREET

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

SHIPTOSTREET2

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

SHIPTOCITY

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

SHIPTOSTATE

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

SHIPTOZIP

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

SHIPTOCOUNTRYCODE

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

Name-Value Pair API Developer Guide

August 2012

167

Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation

BAUpdate API Operation
The BAUpdate API operation updates or deletes a billing agreement.

BAUpdate Request Message

BAUpdate Request Fields
Field

Description

METHOD

(Required) Must be BillAgreementUpdate.

REFERENCEID

(Required) An ID, such as a billing agreement ID or a reference transaction ID that is
associated with a billing agreement.

BILLINGAGREEMENTSTA
TUS

(Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the
value Canceled.
NOTE:

If you do not pass the value Canceled, BAUpdate returns the buyer’s latest
billing address.

L_BILLINGAGREEMENTD
ESCRIPTIONn

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

L_BILLINGAGREEMENTC
USTOMn

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

For recurring payments, this field is ignored.

Character length and limitations: 256 single-byte alphanumeric characters

BAUpdate Response Message

BAUpdate Response Fields

168

Field

Description

L_BILLINGTYPEn

Type of billing agreement.

L_BILLINGAGREEMENTD
ESCRIPTIONn

Description of goods or services associated with the billing agreement. This field is
required for each recurring payment billing agreement.
Character length and limitations: 127 single-byte alphanumeric characters

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation

Field

Description

L_BILLINGAGREEMENTC
USTOMn

Custom annotation field for your own use.
Character length and limitations: 256 single-byte alphanumeric characters

BILLINGAGREEMENTSTA
TUS

(Optional) Use to cancel a billing agreement. To cancel a billing agreement, pass the
value Canceled.
N O TE :

L_BILLINGAGREEMENTM
AXn

If you do not pass the value Canceled, BAUpdate returns the buyer’s latest
billing address.

Maximum amount for this billing agreement.
N O TE :

This field only has a value if the buyer signed up for PayPal using
Preapproved Payments; it is included for backwards compatibility with
legacy systems.

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 (,).
Payer Information Fields
Field

Description

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

PAYERID

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

PAYERSTATUS

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

COUNTRYCODE

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

PAYERBUSINESS

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

Payer Name Fields
Field

Description

SALUTATION

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

FIRSTNAME

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

Name-Value Pair API Developer Guide

August 2012

169

Recurring Payments and Reference Transactions API Operations
BAUpdate API Operation

Field

Description

MIDDLENAME

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

LASTNAME

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

SUFFIX

Buyer’s suffix.
Character length and limitations: 12 single-byte characters
Bill To Address Fields

170

Field

Description

BILLINGNAME

Billing name associated with this billing address.
Character length and limitations: 32 single-byte characters

STREET

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

STREET2

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

CITY

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

STATE

Billing state or province. Required for U.S. addresses only.
Character length and limitations: 40 single-byte characters

ZIP

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

COUNTRYCODE

Billing country code.
Character length and limitations: 2 single-byte characters

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

D o R e f e r e n c e Tr a n s a c t i o n A P I O p e r a t i o n
The DoReferenceTransaction API operation processes a payment from a buyer’s account,
which is identified by a previous transaction.

DoReferenceTransaction Request Message
DoReferenceTransaction Request Fields
Field

Description

METHOD

(Required) Must be DoReferenceTransaction.

REFERENCEID

(Required) A transaction ID from a previous purchase, such as a credit card charge
using the DoDirectPayment API, or a billing agreement ID.

PAYMENTACTION

IPADDRESS

(Optional) IP address of the buyer’s browser.
NOTE:

PayPal records this IP addresses as a means to detect possible fraud.

Character length and limitations: 15 single-byte characters, including periods, for
example, 255.255.255.255
REQCONFIRMSHIPPING

Whether you require that the buyer’s shipping address on file with PayPal be a
confirmed address. You must have permission from PayPal to not require a confirmed
address. It is one of the following values:
 0 – You do not require that the buyer’s shipping address be a confirmed address.
 1 – You require that the buyer’s shipping address be a confirmed address.
NOTE:

Setting this field overrides the setting you have specified in your Merchant
Account Profile.

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

Name-Value Pair API Developer Guide

August 2012

171

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

SOFTDESCRIPTOR

(Optional) Per transaction description of the payment that is passed to the consumer’s
credit card statement.
If the API request provides a value for the soft descriptor field, the full descriptor
displayed on the buyer’s statement has the following format:
<1 space>
The soft descriptor can contain only the following characters:
 Alphanumeric characters
 - (dash)
 * (asterisk)
 . (period)
 {space}
If you use any other characters (such as “,”), PayPal returns an error code. The soft
descriptor does not include the phone number, which can be toggled between the
merchant’s customer service number and PayPal’s customer service number. The
maximum length of the total soft descriptor is 22 characters. Of this, the PayPal prefix
uses either 4 or 8 characters shown in the data format. Thus, the maximum length of
the soft descriptor passed in the API request is:
22 - len() - len( + 1)
For example, assume the following conditions:
 The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.
 The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
 The soft descriptor is passed in as JanesFlowerGifts LLC
The resulting descriptor string on the credit card would be:
PAYPAL *EBAY JanesFlow

PAYMENTREQUEST_n_PA
YMENTREASON

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

MSGSUBID

172

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

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

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

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. Set this field to 0 if the transaction
does not include a one-time purchase such as when you set up a billing agreement for
a recurring payment that is not immediately charged. When the field is set to 0,
purchase-specific fields are ignored.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

CURRENCYCODE

(Optional) A 3-character currency code (default is USD).

ITEMAMT

(Optional) Sum of cost of all items in this order.
NOTE:

ITEMAMT is required if you specify L_AMTn.

Name-Value Pair API Developer Guide

August 2012

173

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

SHIPPINGAMT

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

If you specify a value for SHIPPINGAMT, you must also specify a value for
ITEMAMT.

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

If you specify a value for HANDLINGAMT, you must also specify a value for
ITEMAMT.

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

TAXAMT is required if you specify L_TAXAMTn

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

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

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

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

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

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

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

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

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

174

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

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

NOTIFYURL

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

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

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_ITEMCATEGORYn

Indicates whether the item is digital or physical. For digital goods, this field is
required and you must set it to Digital to get the best rates. These parameters must
be ordered sequentially beginning with 0 (for example L_ITEMCATEGORY0,
L_ITEMCATEGORY1). It is one of the following values:
 Digital
 Physical
This field is introduced in version 69.0.

L_NAMEn

Item name. This field is required when you pass a value for
L_PAYMENTREQUEST_n_ITEMCATEGORYm. These parameters must be ordered
sequentially beginning with 0 (for example L_NAME0, L_NAME1).
Character length and limitations: 127 single-byte characters

L_DESCn

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

L_AMTn

Cost of item. This field is required when you pass a value for
L_PAYMENTREQUEST_n_ITEMCATEGORYm. These parameters must be ordered
sequentially beginning with 0 (for example L_AMT0, L_AMT1).
NOTE:

If you specify a value for L_AMTn, you must specify a value for ITEMAMT.

Name-Value Pair API Developer Guide

August 2012

175

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

L_NUMBERn

(Optional) Item number. These parameters must be ordered sequentially beginning
with 0 (for example L_NUMBER0, L_NUMBER1).
Character length and limitations: 127 single-byte characters

L_QTYn

Item quantity. This field is required when you pass a value for
L_PAYMENTREQUEST_n_ITEMCATEGORYm. These parameters must be ordered
sequentially beginning with 0 (for example L_QTY0, L_QTY1).
Character length and limitations: Any positive integer

L_TAXAMTn

Ebay Item Payment Details Item Fields

176

Field

Description

L_EBAYITEMNUMBERn

(Optional) Auction item number. These parameters must be ordered sequentially
beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1).
Character length: 765 single-byte characters

L_EBAYITEMAUCTIONTX
NIDn

L_EBAYITEMORDERIDn

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Reference Credit Card Details Fields
Field

Description

CREDITCARDTYPE

(Optional) Type of credit card. Is one of the following values:
 Visa
 MasterCard
 Discover
 Amex
 Maestro: See note.
For UK, only Maestro, MasterCard, Discover, and Visa are allowable. For
Canada, only MasterCard and Visa are allowable. Interac debit cards are not
supported.
NOTE:

If the credit card type is Maestro, you must set CURRENCYCODE to GBP. In
addition, you must specify either STARTDATE or ISSUENUMBER.

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

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

EXPDATE

CVV2

(Optional) Card Verification Value, version 2. To comply with credit card processing
regulations, you must not store this value after a transaction has been completed.
Character length and limitations: For Visa, MasterCard, and Discover, the value is
exactly 3 digits. For American Express, the value is exactly 4 digits.

STARTDATE

(Optional) Month and year that Maestro card was issued.
Character length and limitations: Must be 6 digits, including leading zero, in the
format MMYYYY

ISSUENUMBER

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

Payer Information Fields
Field

Description

(Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters

FIRSTNAME

(Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters

Name-Value Pair API Developer Guide

August 2012

177

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

LASTNAME

(Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Address Fields

Field

Description

STREET

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

STREET2

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

CITY

(Optional) Name of city.
Character length and limitations: 40 single-byte characters

STATE

(Optional) State or province.
Character length and limitations: 40 single-byte characters

COUNTRYCODE

(Optional) Country code.
Character limit: 2 single-byte characters

ZIP

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

SHIPTOPHONENUM

(Optional) Phone number.
Character length and limit: 20 single-byte characters

DoReferenceTransaction Response Message

DoReferenceTransaction Response Fields for Express Checkout

178

Field

Description

AVSCODE

Address Verification System response code.
Character limit: 1 single-byte alphanumeric character

CVV2MATCH

Result of the CVV2 check by PayPal.

BILLINGAGREEMENTID

Billing agreement identifier returned if the value of ReferenceID in the request is a
billing agreement identification number.

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

L_FMFfilterIDn

L_FMFfilterNAMEn

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 recurring transaction is declined. For
details on the meanings of the codes, see https://merchant.paypal.com/us/cgibin/?&cmd=_render-content&content_ID=merchant/cc_compliance_error_codes
This field is available since version 84.0.

MSGSUBID

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

August 2012

179

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

PARENTTRANSACTIONID

RECEIPTID

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

TRANSACTIONTYPE

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

PAYMENTTYPE

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

180

ORDERTIME

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

AMT

CURRENCYCODE

A 3-character currency code.

FEEAMT

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

SETTLEAMT

TAXAMT

EXCHANGERATE

Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency. If the buyer chooses to pay with a currency other than the
non-primary currency, the conversion occurs in the buyer’s account.
Character length and limitations: Decimal value that does not exceed 17 characters,
including decimal point

PAYMENTSTATUS

Name-Value Pair API Developer Guide

August 2012

181

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

PENDINGREASON

REASONCODE

182

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

August 2012

Name-Value Pair API Developer Guide

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

Field

Description

PROTECTIONELIGIBILI
TY

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

PROTECTIONELIGIBILI
TYTYPE

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

This field is introduced in API version 64.4.
STOREID

xs:string
StoreId as entered in the transaction.

TERMINALID

xs:string
TerminalId as entered in the transaction.

Name-Value Pair API Developer Guide

August 2012

183

184

Recurring Payments and Reference Transactions API Operations
DoReferenceTransaction API Operation

August 2012

Name-Value Pair API Developer Guide

RefundTransaction API Operation

The RefundTransaction API operation issues a refund to the PayPal account holder associated
with a transaction.

RefundTransaction Request Message

RefundTransaction Request Fields
Field

Description

METHOD

(Required) Must be RefundTransaction.

TRANSACTIONID

(Required) Unique identifier of the transaction to be refunded.
Character length and limitations: 17 single-byte alphanumeric characters

INVOICEID

(Optional) Your own invoice or tracking number.
Character length and limitations: 127 single-byte alphanumeric characters

REFUNDTYPE

Type of refund you are making. It is one of the following values:
 Full – Full refund (default).
 Partial – Partial refund.
 ExternalDispute – External dispute. (Value available since version 82.0)
 Other – Other type of refund. (Value available since version 82.0)

AMT

(Optional) Refund amount. The amount is required if RefundType is Partial.
NOTE:

If RefundType is Full, do not set the amount.

ISO 4217 3-letter currency code. USD for US Dollars. This field is required for
partial refunds, and is also required for refunds greater than 100%.
Character length and limitations: 3 single-byte characters

NOTE

(Optional) Custom memo about the refund.
Character length and limitations: 255 single-byte alphanumeric characters

Name-Value Pair API Developer Guide

August 2012

185

RefundTransaction API Operation
RefundTransaction Request Message

Field

Description

RETRYUNTIL

(Optional) Maximum time until you must retry the refund.
NOTE:

This field does not apply to point-of-sale transactions.

This field is available since version 82.0.
REFUNDSOURCE

(Optional)Type of PayPal funding source (balance or eCheck) that can be used for
auto refund. It is one of the following values:
 any – The merchant does not have a preference. Use any available funding
source.
 default – Use the merchant’s preferred funding source, as configured in the
merchant’s profile.
 instant – Use the merchant’s balance as the funding source.
 eCheck – The merchant prefers using the eCheck funding source. If the
merchant’s PayPal balance can cover the refund amount, use the PayPal balance.
NOTE:

This field does not apply to point-of-sale transactions.

This field is available since version 82.0.
MERCHANTSTOREDETAIL
S

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

REFUNDADVICE

(Optional) Flag to indicate that the buyer was already given store credit for a given
transaction. It is one of the following values:
 true – The buyer was already given store credit for a given transaction.
 false – The buyer was not given store credit for a given transaction.
This field is available since version 85.0.

REFUNDITEMDETAILS

(Optional) Details about the individual items to be returned.

MSGSUBID

Merchant Store Details Fields

186

Field

Description

STOREID

August 2012

Name-Value Pair API Developer Guide

RefundTransaction API Operation
RefundTransaction Response Message

Field

Description

TERMINALID

(Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.

RefundTransaction Response Message

RefundTransaction Response Fields
Field

Description

REFUNDTRANSACTIONID

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

FEEREFUNDAMT

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

GROSSREFUNDAMT

Amount refunded to the original payer. Say, for example, a buyer makes $100
purchase, the buyer was refunded $20 a week ago and is refunded $30 in this
transaction. The gross refund amount is $30 (in this transaction).
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

NETREFUNDAMT

Amount subtracted from PayPal balance of the original recipient of payment, to make
this refund.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).

TOTALREFUNDEDAMT

Total amount refunded so far from the original purchase. Say, for example, a buyer
makes $100 purchase, the buyer was refunded $20 a week ago and is refunded $30 in
this transaction. The gross refund amount is $30 (in this transaction). The total
refunded amount is $50.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
This field is available since version 67.0.

Name-Value Pair API Developer Guide

August 2012

187

RefundTransaction API Operation
RefundTransaction Response Message

Field

Description

CURRENCYCODE

Currency code.
Character length and limitations: 3 single-byte characters

REFUNDINFO

Contains refund payment status information.
This field is available since version 84.0.

MSGSUBID

RefundInfoType Fields
Field

Description

REFUNDSTATUS

ns:PaymentStatusCodeType
Status of the refund. It is one of the following values:
 instant
 delayed
This field is available since version 84.0.

PENDINGREASON

Reason that the refund payment status is delayed. It is one of the following values:
 none – The refund status is instant.
 echeck – The refund status is delayed.
This field is available since version 84.0.

188

August 2012

Name-Value Pair API Developer Guide

TransactionSearch API Operation

The TransactionSearch API searches transaction history for transactions that meet the
specified criteria.
NOT E :

The maximum number of transactions that can be returned from a TransactionSearch
API call is 100.

TransactionSearch Request Message

TransactionSearch Request Fields
Field

Description

METHOD

(Required) Must be TransactionSearch.

STARTDATE

(Required) The earliest transaction date at which to start the search.
Character length and limitations: No wildcards are allowed. The value must be in
UTC/GMT.

ENDDATE

(Optional) The latest transaction date to be included in the search.
Character length and limitations: No wildcards are allowed. The value must be in
UTC/GMT.

(Optional) Search by the buyer’s email address.
Character length and limitations: 127 single-byte alphanumeric characters

RECEIVER

(Optional) Search by the receiver’s email address. If the merchant account has only
one email address, this is the primary email. It can also be a non-primary email
address.

RECEIPTID

(Optional) Search by the PayPal Account Optional receipt ID. This field is not
applicable to point-of-sale transactions.

TRANSACTIONID

(Optional) Search by the transaction ID. The returned results are from the merchant’s
transaction records.
Character length and limitations: 19 single-byte characters maximum

INVNUM

(Optional) Search by invoice identification key, as set by you for the original
transaction. This field searches the records for items the merchant sells.
Character length and limitations: 127 single-byte characters maximum with no
wildcards allowed

Name-Value Pair API Developer Guide

August 2012

189

TransactionSearch API Operation
TransactionSearch Request Message

Field

Description

ACCT

(Optional) Search by credit card number, as set by you for the original transaction.
This field searches the records for items the merchant sells. The field is not applicable
to point-of-sale.
NOTE:

No wildcards are allowed.

Character length and limitations: Must be at least 11 and no more than 25 single-byte
numeric characters maximum. Special punctuation, such as dashes or spaces, is
ignored.
AUCTIONITEMNUMBER

(Optional) Search by auction item number of the purchased goods. This field is not
applicable to point-of-sale.

TRANSACTIONCLASS

(Optional) Search by classification of transaction. Some kinds of possible classes of
transactions are not searchable with this field. You cannot search for bank transfer
withdrawals, for example. It is one of the following values:
 All – All transaction classifications
 Sent – Only payments sent
 Received – Only payments received
 MassPay – Only mass payments
 MoneyRequest – Only money requests
 FundsAdded – Only funds added to balance
 FundsWithdrawn – Only funds withdrawn from balance
 Referral – Only transactions involving referrals
 Fee – Only transactions involving fees
 Subscription – Only transactions involving subscriptions
 Dividend – Only transactions involving dividends
 Billpay – Only transactions involving BillPay Transactions
 Refund – Only transactions involving funds
 CurrencyConversions – Only transactions involving currency conversions
 BalanceTransfer – Only transactions involving balance transfers
 Reversal – Only transactions involving BillPay reversals
 Shipping – Only transactions involving UPS shipping fees
 BalanceAffecting – Only transactions that affect the account balance
 ECheck – Only transactions involving eCheck

AMT

(Optional) Search by transaction amount.
NOTE:

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

190

(Optional) Search by 3-character, ISO 4217 currency code.

August 2012

Name-Value Pair API Developer Guide

TransactionSearch API Operation
TransactionSearch Request Message

Field

Description

STATUS

(Optional) Search by transaction status. It is one of the following values:
 Pending – The payment is pending. The specific reason the payment is pending
is returned by the GetTransactionDetails API PendingReason field.
 Processing – The payment is being processed.
 Success – The payment has been completed and the funds have been added
successfully to your account balance.
 Denied – You denied the payment. This happens only if the payment was
previously pending.
 Reversed – A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer.

PROFILEID

(Optional) An alphanumeric string (generated by PayPal) that uniquely identifies a
recurring profile. You can specify the Profile ID in the TransactionSearch API
operation to obtain all payments associated with the identified profile.

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

Name-Value Pair API Developer Guide

August 2012

191

TransactionSearch API Operation
TransactionSearch Response Message

Tr a n s a c t i o n S e a r c h R e s p o n s e M e s s a g e

TransactionSearch Response Fields

192

Field

Description

L_TIMESTAMPn

Date and time in UTC/GMT that the transaction occurred.

L_TIMEZONEn

Time zone of the transaction. The value is always GMT.

L_TYPEn

Type of the transaction. It is one of the following values:
 Currency Conversion (credit)
 Currency Conversion (debit)
 Payment
 Recurring Payment
 Temporary Hold
 Transfer
 Donation

L_EMAILn

Email address of either the buyer or the payment recipient (the “payee”). If the
payment amount is positive, this field is the recipient of the funds. If the payment is
negative, this field is the paying buyer.

L_NAMEn

Display name of the buyer.

L_TRANSACTIONIDn

Merchant’s transaction ID.

L_STATUSn

The status of the transaction.

L_AMTn

The total gross amount charged, including any profile shipping cost and taxes.

L_CURRENCYCODEn

3-character, ISO 4217 currency code.

L_FEEAMTn

The fee that PayPal charged for the transaction.

L_NETAMTn

The net amount of the transaction.

August 2012

Name-Value Pair API Developer Guide

API Error Codes

The PayPal API can return multiple errors for any operation.

General API Errors
General API Errors
Error
Code

Short Message

Long Message

Correcting This Error

10002

Authentication/Authoriza
tion Failed

Username/Password is incorrect

This error can be caused by an incorrect
API username, an incorrect API
password, or an invalid API signature.
Make sure that all three of these values
are correct. For your security, PayPal
does not report exactly which of these
three values might be in error.

10002

Authentication/Authoriza
tion Failed

You do not have permission to
make this API call

10002

Authentication/Authoriza
tion Failed

Account is locked or inactive

10002

Internal Error

10002

Authentication/Authoriza
tion Failed

Internal Error

10002

Authentication/Authoriza
tion Failed

Account is not verified

10002

Authentication/Authoriza
tion Failed

This call is not defined in the
database!

10002

Authentication/Authoriza
tion Failed

Token is not valid

10002

Restricted account

Account is restricted

10002

Authentication/Authoriza
tion Failed

API access is disabled for this
account

Name-Value Pair API Developer Guide

August 2012

Your PayPal merchant account has been
restricted. Contact your PayPal account
manager for resolution.

193

API Error Codes
Validation Errors

Error
Code

Short Message

Long Message

Correcting This Error

10002

Authentication/Authoriza
tion Failed

Client certificate is disabled

10006

Version error

Version is not supported

10008

Security error

Security header is not valid

10101

This API Temporarily
Unavailable

This API is temporarily
unavailable. Please try later.

Validation Errors
Validation Errors

194

Error Code

Short Message

Long Message

81000

Missing Parameter

Required Parameter Missing : Unable to identify
parameter

81001

Invalid Parameter

A Parameter is Invalid : Unable to identify parameter

81002

Unspecified Method

Method Specified is not Supported

81003

Unspecified Method

No Method Specified

81004

Unspecified Method

No Request Received

81100

Missing Parameter

OrderTotal (Amt) : Required parameter missing

81101

Missing Parameter

MaxAmt : Required parameter missing

81102

Missing Parameter

ReturnURL: Required parameter missing

81103

Missing Parameter

NotifyURL : Required parameter missing

81104

Missing Parameter

CancelURL : Required parameter missing

81105

Missing Parameter

ShipToStreet : Required parameter missing

81106

Missing Parameter

ShipToStreet2 : Required parameter missing

81107

Missing Parameter

ShipToCity : Required parameter missing

81108

Missing Parameter

ShipToState : Required parameter missing

81109

Missing Parameter

ShipToZip : Required parameter missing

81110

Missing Parameter

Country : Required parameter missing

81111

Missing Parameter

ReqConfirmShipping : Required parameter missing

81112

Missing Parameter

NoShipping : Required parameter missing

81113

Missing Parameter

AddrOverride : Required parameter missing

August 2012

Name-Value Pair API Developer Guide

API Error Codes
Validation Errors

Error Code

Short Message

Long Message

81114

Missing Parameter

LocaleCode : Required parameter missing

81115

Missing Parameter

PaymentAction : Required parameter missing

81116

Missing Parameter

Email : Required parameter missing

81117

Missing Parameter

Token : Required parameter missing

81118

Missing Parameter

PayerID : Required parameter missing

81119

Missing Parameter

ItemAmt : Required parameter missing

81120

Missing Parameter

ShippingAmt : Required parameter missing

81121

Missing Parameter

HandlingAmt : Required parameter missing

81122

Missing Parameter

TaxAmt : Required parameter missing

81123

Missing Parameter

IPAddress : Required parameter missing

81124

Missing Parameter

ShipToName : Required parameter missing

81125

Missing Parameter

L_Amt : Required parameter missing

81126

Missing Parameter

Amt : Required parameter missing

81127

Missing Parameter

L_TaxAmt : Required parameter missing

81128

Missing Parameter

AuthorizationID : Required parameter missing

81129

Missing Parameter

CompleteType : Required parameter missing

81130

Missing Parameter

CurrencyCode : Required parameter missing

81131

Missing Parameter

TransactionID : Required parameter missing

81132

Missing Parameter

TransactionEntity : Required parameter missing

81133

Missing Parameter

Acct : Required parameter missing

81134

Missing Parameter

ExpDate : Required parameter missing

81135

Missing Parameter

FirstName : Required parameter missing

81136

Missing Parameter

LastName : Required parameter missing

81137

Missing Parameter

Street : Required parameter missing

81138

Missing Parameter

Street2 : Required parameter missing

81139

Missing Parameter

City : Required parameter missing

81140

Missing Parameter

State : Required parameter missing

81141

Missing Parameter

Zip : Required parameter missing

81142

Missing Parameter

CountryCode : Required parameter missing

81143

Missing Parameter

RefundType : Required parameter missing

81144

Missing Parameter

StartDate : Required parameter missing

Name-Value Pair API Developer Guide

August 2012

195

196

API Error Codes
Validation Errors

Error Code

Short Message

Long Message

81145

Missing Parameter

EndDate : Required parameter missing

81146

Missing Parameter

MPID : Required parameter missing

81147

Missing Parameter

CreditCardType : Required parameter missing

81148

Missing Parameter

User : Required parameter missing

81149

Missing Parameter

Pwd : Required parameter missing

81150

Missing Parameter

Version : Required parameter missing

81200

Missing Parameter

Amt : Invalid parameter

81201

Invalid Parameter

MaxAmt : Invalid parameter

81203

Invalid Parameter

NotifyURL : Invalid parameter

81205

Invalid Parameter

ShipToStreet : Invalid parameter

81206

Invalid Parameter

ShipToStreet2 : Invalid parameter

81207

Invalid Parameter

ShipToCity : Invalid parameter

81208

Invalid Parameter

ShipToState : Invalid parameter

81209

Invalid Parameter

ShipToZip : Invalid parameter

81210

Invalid Parameter

Country : Invalid parameter

81211

Invalid Parameter

ReqConfirmShipping : Invalid parameter

81212

Invalid Parameter

Noshipping : Invalid parameter

81213

Invalid Parameter

AddrOverride : Invalid parameter

81214

Invalid Parameter

LocaleCode : Invalid parameter

81215

Invalid Parameter

PaymentAction : Invalid parameter

81219

Invalid Parameter

ItemAmt : Invalid parameter

81220

Invalid Parameter

ShippingAmt : Invalid parameter

81221

Invalid Parameter

HandlingTotal Amt : Invalid parameter

81222

Invalid Parameter

TaxAmt : Invalid parameter

81223

Invalid Parameter

IPAddress : Invalid parameter

81224

Invalid Parameter

ShipToName : Invalid parameter

81225

Invalid Parameter

L_Amt : Invalid parameter

81226

Invalid Parameter

Amt : Invalid parameter

81227

Invalid Parameter

L_TaxAmt : Invalid parameter

81229

Invalid Parameter

CompleteType : Invalid parameter

81230

Invalid Parameter

CurrencyCode : Invalid parameter

August 2012

Name-Value Pair API Developer Guide

API Error Codes
DirectPayment API Errors

Error Code

Short Message

Long Message

81232

Invalid Parameter

TransactionEntity : Invalid parameter

81234

Invalid Parameter

ExpDate : Invalid parameter

81235

Invalid Parameter

FirstName : Invalid parameter

81236

Invalid Parameter

LastName : Invalid parameter

81237

Invalid Parameter

Street : Invalid parameter

81238

Invalid Parameter

Street2 : Invalid parameter

81239

Invalid Parameter

City : Invalid parameter

81243

Invalid Parameter

RefundType : Invalid parameter

81244

Invalid Parameter

StartDate : Invalid parameter

81245

Invalid Parameter

EndDate : Invalid parameter

81247

Invalid Parameter

CreditCardType : Invalid parameter

81248

Invalid Parameter

Username : Invalid parameter

81249

Invalid Parameter

Password : Invalid parameter

81250

Invalid Parameter

Version : Invalid parameter

81251

Internal Error

Internal Service Error

99998

Transaction refused because of an
invalid argument. See additional
error messages for details.

Currency is not supported

DirectPayment API Errors
DirectPayment API Errors
Error
Code

Short Message

Long Message

10102

PaymentAction of Order
Temporarily Unavailable

PaymentAction of Order is
temporarily unavailable. Please
try later or use other
PaymentAction.

10401

Order total is missing.
Transaction refused
because of an invalid
argument. See additional
error messages for details.

Name-Value Pair API Developer Guide

August 2012

Corrective Action

197

API Error Codes
DirectPayment API Errors

Error
Code

198

Short Message

Long Message

Corrective Action

10418

The currencies of the shopping
Transaction refused
cart amounts must be the same.
because of an invalid
argument. See additional
error messages for details.

10426

Item total is invalid.
Transaction refused
because of an invalid
argument. See additional
error messages for details.

10427

Shipping total is invalid.
Transaction refused
because of an invalid
argument. See additional
error messages for details.

10428

Handling total is invalid.
Transaction refused
because of an invalid
argument. See additional
error messages for details.

10429

Tax total is invalid.
Transaction refused
because of an invalid
argument. See additional
error messages for details.

10432

Invalid argument

Invoice ID value exceeds
maximum allowable length.

10485

Payment not authorized

Payment has not been authorized
by the user.

10500

Invalid Configuration

This transaction cannot be
processed due to an invalid
merchant configuration.

Occurs when you have not agreed to the
billing agreement.

10501

Invalid Configuration

This transaction cannot be
processed due to an invalid
merchant configuration.

Occurs when the billing agreement is
disabled or inactive.

10502

Invalid Data

This transaction cannot be
processed. Please use a valid
credit card.

The credit card used is expired.

10504

Invalid Data

This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.

The CVV provided is invalid. The CVV
is between 3-4 digits long.

10505

Gateway Decline

This transaction cannot be
processed.

The transaction was refused because the
AVS response returned the value of N,
and the merchant account is not able to
accept such transactions.

August 2012

Name-Value Pair API Developer Guide

API Error Codes
DirectPayment API Errors

Error
Code

Short Message

Long Message

Corrective Action

10507

Invalid Configuration

This transaction cannot be
processed. Please contact PayPal
Customer Service.

Your PayPal account is restricted.
Contact PayPal for more information.

10508

Invalid Data

This transaction cannot be
processed. Please enter a valid
credit card expiration date.

The expiration date must be a two-digit
month and four-digit year.

10509

Invalid Data

This transaction cannot be
processed.

You must submit an IP address of the
buyer with each API call.

10510

Invalid Data

The credit card type is not
supported. Try another card type.

The credit card type entered is not
currently supported by PayPal.

10511

Invalid Data

This transaction cannot be
processed.

The merchant selected a value for the
PaymentAction field that is not
supported.

10512

Invalid Data

This transaction cannot be
processed. Please enter a first
name.

The first name of the buyer is required
for this merchant.

10513

Invalid Data

This transaction cannot be
processed. Please enter a last
name.

The last name of the buyer is required
for this merchant.

10519

Invalid Data

Please enter a credit card.

The credit card field was blank.

10520

Invalid Data

This transaction cannot be
processed.

The total amount and item amounts do
not match.

10521

Invalid Data

This transaction cannot be
processed. Please enter a valid
credit card.

The credit card entered is invalid.

10523

Internal Error

This transaction cannot be
processed.

None. This is a PayPal internal error.

10525

Invalid Data

This transaction cannot be
processed. The amount to be
charged is zero.

The merchant entered an amount of zero.

10526

Invalid Data

This transaction cannot be
processed. The currency is not
supported at this time.

The currency code entered is not
supported.

10527

Invalid Data

This transaction cannot be
processed. Please enter a valid
credit card number and type.

The credit card entered is invalid.

10534

Gateway Decline

This transaction cannot be
processed. Please enter a valid
credit card number and type.

The credit card entered is currently
restricted by PayPal. Contact PayPal for
more information.

Name-Value Pair API Developer Guide

August 2012

199

200

API Error Codes
DirectPayment API Errors

Error
Code

Short Message

Long Message

Corrective Action

10535

Gateway Decline

This transaction cannot be
processed. Please enter a valid
credit card number and type.

The credit card entered is invalid.

10536

Invalid Data

This transaction cannot be
processed.

The merchant entered an invoice ID that
is already associated with a transaction
by the same merchant. By default, the
invoice ID must be unique for all
transactions. To change this setting, log
into PayPal or contact customer service.

10537

Filter Decline

This transaction cannot be
processed.

The transaction was declined by the
country filter managed by the merchant.
To accept this transaction, change your
risk settings on PayPal.

10538

Filter Decline

This transaction cannot be
processed.

The transaction was declined by the
maximum amount filter managed by the
merchant. To accept this transaction,
change your risk settings on PayPal.

10539

Filter Decline

This transaction cannot be
processed.

The transaction was declined by PayPal.
Contact PayPal for more information.

10540

Invalid Data

The transaction cannot be
processed due to an invalid
address.

The transaction was declined by PayPal
because of an invalid address.

10541

Gateway Decline

This transaction cannot be
processed. Please enter a valid
credit card number and type.

The credit card entered is currently
restricted by PayPal. Contact PayPal for
more information.

10542

Invalid Data

This transaction cannot be
processed. Please enter a valid
email address.

The email address provided by the buyer
is in an invalid format.

10544

Gateway Decline

This transaction cannot be
processed.

The transaction was declined by PayPal.
Contact PayPal for more information.

10545

Gateway Decline

This transaction cannot be
processed.

The transaction was declined by PayPal
because of possible fraudulent activity.
Contact PayPal for more information.

10546

Gateway Decline

This transaction cannot be
processed.

The transaction was declined by PayPal
because of possible fraudulent activity
on the IP address. Contact PayPal for
more information.

10547

Internal Error

This transaction cannot be
processed.

None. This is a PayPal internal error.

August 2012

Name-Value Pair API Developer Guide

API Error Codes
DirectPayment API Errors

Error
Code

Short Message

Long Message

Corrective Action

10548

Invalid Configuration

This transaction cannot be
processed. The merchant’s
account is not able to process
transactions.

The merchant account attempting the
transaction is not a business account at
PayPal. Check your account settings.

10549

Invalid Configuration

This transaction cannot be
processed. The merchan’s
account is not able to process
transactions.

The merchant account attempting the
transaction is not able to process Direct
Payment transactions. Contact PayPal
for more information.

10550

Invalid Configuration

This transaction cannot be
processed.

Access to Direct Payment was disabled
for your account. Contact PayPal for
more information.

10552

Invalid Configuration

This transaction cannot be
processed.

The merchant account attempting the
transaction does not have a confirmed
email address with PayPal. Check your
account settings.

10553

Gateway Decline

This transaction cannot be
processed.

The merchant attempted a transaction
where the amount exceeded the upper
limit for that merchant.

10554

Filter Decline

This transaction cannot be
processed.

The transaction was declined because of
a merchant risk filter for AVS.
Specifically, the merchant has set to
decline transaction when the AVS
returned a no match (AVS = N).

10555

Filter Decline

This transaction cannot be
processed.

The transaction was declined because of
a merchant risk filter for AVS.
Specifically, the merchant has set the
filter to decline transactions when the
AVS returns a partial match.

10556

Filter Decline

This transaction cannot be
processed.

The transaction was declined because of
a merchant risk filter for AVS.
Specifically, the merchant has set the
filter to decline transactions when the
AVS is unsupported.

10561

Invalid Data

There’s an error with this
transaction. Please enter
complete billing address.

10562

Invalid Data

This transaction cannot be
processed. Please enter a valid
credit card expiration year.

10563

Invalid Data

This transaction cannot be
processed. Please enter a valid
credit card expiration month.

Name-Value Pair API Developer Guide

August 2012

201

202

API Error Codes
DirectPayment API Errors

Error
Code

Short Message

Long Message

Corrective Action

10564

Gateway Decline

This transaction cannot be
processed.

There was a problem processing this
transaction.

10565

Merchant country
unsupported

The merchant country is not
supported.

10566

Credit card type
unsupported

The credit card type is not
supported.

10567

Invalid Data

This transaction cannot be
processed. Please enter a valid
credit card number and type.

10571

Transaction approved, but
with invalid Card
Security Code (CSC)
format.

This transaction was approved,
although the Card Security Code
(CSC) had too few, too many, or
invalid characters. Based on your
account profile settings, the
invalid CSC was not given to the
card issuer for its approval
process.

If you want to require valid CVV values,
change the risk control settings in your
account profile.

10701

Invalid Data

There’s an error with this
transaction. Please enter a valid
billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10702

Invalid Data

There’s an error with this
transaction. Please enter a valid
address1 in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10703

Invalid Data

There’s an error with this
transaction. Please enter a valid
address2 in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10704

Invalid Data

There’s an error with this
transaction. Please enter a valid
city in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10705

Invalid Data

There’s an error with this
transaction. Please enter a valid
state in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10706

Invalid Data

There’s an error with this
transaction. Please enter a valid
postal code in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10707

Invalid Data

There’s an error with this
transaction. Please enter a valid
country in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

August 2012

Name-Value Pair API Developer Guide

API Error Codes
DirectPayment API Errors

Error
Code

Short Message

Long Message

Corrective Action

10708

Invalid Data

There’s an error with this
transaction. Please enter a
complete billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10709

Invalid Data

There’s an error with this
transaction. Please enter an
address1 in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10709

Invalid Data

There’s an error with this
transaction. Please enter an
address1 in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10710

Invalid Data

There’s an error with this
transaction. Please enter a city in
the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10710

Invalid Data

There’s an error with this
transaction. Please enter a city in
the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10711

Invalid Data

There’s an error with this
transaction. Please enter your
state in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10712

Invalid Data

There’s an error with this
transaction. Please enter your
five digit postal code in the
billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10713

Invalid Data

There’s an error with this
transaction. Please enter a
country in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10713

Invalid Data

There’s an error with this
transaction. Please enter a
country in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10714

Invalid Data

There’s an error with this
transaction. Please enter a valid
billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10715

Invalid Data

There’s an error with this
transaction. Please enter a valid
state in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10716

Invalid Data

There’s an error with this
transaction. Please enter your
five digit postal code in the
billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

Name-Value Pair API Developer Guide

August 2012

203

204

API Error Codes
DirectPayment API Errors

Error
Code

Short Message

Long Message

Corrective Action

10717

Invalid Data

There’s an error with this
transaction. Please enter a valid
postal code in the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10718

Invalid Data

There’s an error with this
transaction. Please enter a valid
city and state in the billing
address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10719

Invalid Data

There’s an error with this
transaction. Please enter a valid
shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10720

Invalid Data

There’s an error with this
transaction. Please enter a valid
address1 in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10721

Invalid Data

There’s an error with this
transaction. Please enter a valid
address2 in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10722

Invalid Data

There’s an error with this
transaction. Please enter a valid
city in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10723

Invalid Data

There’s an error with this
transaction. Please enter a valid
state in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10724

Invalid Data

There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10725

Invalid Data

There’s an error with this
transaction. Please enter a valid
country in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10726

Invalid Data

There’s an error with this
transaction. Please enter a
complete shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10726

Invalid Data

There’s an error with this
transaction. Please enter a
complete shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10727

Invalid Data

There’s an error with this
transaction. Please enter an
address1 in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

August 2012

Name-Value Pair API Developer Guide

API Error Codes
DirectPayment API Errors

Error
Code

Short Message

Long Message

Corrective Action

10727

Invalid Data

There’s an error with this
transaction. Please enter an
address1 in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10728

Invalid Data

There’s an error with this
transaction. Please enter a city in
the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10728

Invalid Data

There’s an error with this
transaction. Please enter a city in
the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10729

Invalid Data

There’s an error with this
transaction. Please enter your
state in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10730

Invalid Data

There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10731

Invalid Data

There’s an error with this
transaction. Please enter a
country in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10731

Invalid Data

There’s an error with this
transaction. Please enter a
country in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10732

Invalid Data

There’s an error with this
transaction. Please enter a valid
shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10733

Invalid Data

There’s an error with this
transaction. Please enter a valid
state in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10734

Invalid Data

There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10735

Invalid Data

There’s an error with this
transaction. Please enter your
five digit postal code in the
shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10736

Invalid Data

There’s an error with this
transaction. Please enter a valid
city and state in the shipping
address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

Name-Value Pair API Developer Guide

August 2012

205

206

API Error Codes
DirectPayment API Errors

Error
Code

Short Message

Long Message

Corrective Action

10744

Invalid Data

This transaction cannot be
processed. Please enter a valid
country code in the billing
address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10745

Invalid Data

This transaction cannot be
processed. Please enter a valid
country code in the shipping
address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10746

Invalid Data

This transaction cannot be
processed. Please use a valid
country on the billing address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10747

Invalid Data

This transaction cannot be
processed.

The merchant entered an IP address that
was in an invalid format. The IP address
must be in a format such as
123.456.123.456.

10748

Invalid Data

This transaction cannot be
processed without a Credit Card
Verification Number.

The merchant’s configuration requires a
CVV to be entered, but no CVV was
provided with this transaction. Contact
PayPal if you wish to change this setting.

10750

Invalid Data

There’s an error with this
transaction. Please enter a valid
state in the shipping address.

There was a problem with a particular
field in the address. The long error
message tells you which field is invalid.

10751

Invalid Data

There’s an error with this
transaction. Please enter a valid
state in the billing address.

The merchant provided an address either
in the United States or Canada, but the
state provided is not a valid state in
either country.

10752

Gateway Decline

This transaction cannot be
processed.

The transaction was declined by the
issuing bank, not PayPal. The merchant
should attempt another card.

10754

Gateway Decline

This transaction cannot be
processed.

The transaction was declined by PayPal.
Contact PayPal for more information.

10755

Invalid Data

This transaction cannot be
processed due to an unsupported
currency.

The currency code entered by the
merchant is not supported.

10756

Gateway Decline

The transaction cannot be
processed. The country and
billing address associated with
this credit card do not match.

None. This is a PayPal internal error.

10758

Invalid Configuration

There’s been an error due to
invalid API username and/or
password.

The API username or password is
incorrect for this merchant.

August 2012

Name-Value Pair API Developer Guide

API Error Codes
DirectPayment API Errors

Error
Code

Short Message

Long Message

Corrective Action

10759

Gateway Decline

This transaction cannot be
processed. Please enter a valid
credit card number and type.

The transaction was declined by PayPal.
Contact PayPal for more information.

10760

Invalid Configuration

This transaction cannot be
processed. The country listed for
your business address is not
currently supported.

The merchant’s country of residence
listed in their PayPal account is not
currently supported to allow Direct
Payment transactions.

10761

Gateway Decline

This transaction cannot be
processed. Please check the
status of your first transaction
before placing another order.

The transaction was declined because
PayPal is currently processing a
transaction by the same buyer for the
same amount. Can occur when a buyer
submits multiple, identical transactions
in quick succession.

10762

Gateway Decline

This transaction cannot be
processed.

The CVV provide is invalid. The CVV is
between 3-4 digits long.

10763

Invalid Data

This transaction cannot be
processed.

None - this is a PayPal internal error.

10764

This transaction cannot be
processed at this time.
Please try again later.

This transaction cannot be
processed at this time. Please try
again later.

The transaction was declined by PayPal.
Please try again later. If the problem
persists, please contact PayPal.

11068

Seller restriction.

All sellers restricted.

11610

Payment Pending your
review in Fraud
Management Filters

Payment Pending your review in
Fraud Management Filters

11611

Transaction blocked by
your settings in FMF

Transaction blocked by your
settings in FMF

11612

Could not process your
request to accept/deny the
transaction

Could not process your request to
accept/deny the transaction

11821

This transaction cannot be
processed

This transaction cannot be
processed because it has already
been denied by a Fraud
Management Filter

You cannot capture a payment after it
has been denied by a Fraud Management
Filter. You can control whether a Fraud
Management Filter denies a transaction
by changing the filter's settings in the
profile.

12000

Transaction is not
compliant due to missing
or invalid 3-D Secure
authentication values.

Transaction is not compliant due
to missing or invalid 3-D Secure
authentication values.

Check ECI, ECI3DS, CAVV, XID fields.

Name-Value Pair API Developer Guide

August 2012

207

API Error Codes
DirectPayment API Errors

Error
Code

208

Short Message

Long Message

Corrective Action

12001

Transaction is not
compliant due to missing
or invalid 3-D Secure
authentication values.

Transaction is not compliant due
to missing or invalid 3-D Secure
authentication values.

Check ECI, ECI3DS, CAVV, XID fields.

15001

Gateway Decline

This transaction cannot be
processed.

The transaction was rejected by PayPal
because of excessive failures over a
short period of time for this credit card.
Contact PayPal for more information.

15002

Gateway Decline

This transaction cannot be
processed.

The transaction was declined by PayPal.
Contact PayPal for more information.

15003

Invalid Configuration

This transaction cannot be
processed.

The transaction was declined because
the merchant does not have a valid
commercial entity agreement on file
with PayPal. Contact PayPal for more
information.

15004

Gateway Decline

This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.

The transaction was declined because
the CVV entered does not match the
credit card.

15005

Processor Decline

This transaction cannot be
processed.

The transaction was declined by the
issuing bank, not PayPal. The merchant
should attempt another card.

15006

Processor Decline

This transaction cannot be
processed. Please enter a valid
credit card number and type.

The transaction was declined by the
issuing bank, not PayPal. The merchant
should attempt another card.

15007

Processor Decline

This transaction cannot be
processed. Please use a valid
credit card.

The transaction was declined by the
issuing bank because of an expired
credit card. The merchant should attempt
another card.

15008

Invalid Data

This transaction has been
completed, but the total of items
in the cart did not match the total
of all items.

15011

Gateway Decline

This credit card was issued from
an unsupported country.

August 2012

Name-Value Pair API Developer Guide

API Error Codes
SetExpressCheckout API Errors

SetExpressCheckout API Errors
SetExpressCheckout API Errors
Error
Code

Short Message

Long Message

10001

ButtonSource value
truncated.

The transaction could not be loaded

10001

Internal Error

10003

Missing argument.

OtherPaymentMethodID is missing.

10003

Missing argument.

OtherPaymentMethodLabel is
missing.

10003

Missing argument.

OtherPaymentMethodType is
missing.

10003

Missing argument.

One or more of these giropay URLs
is missing: giropaySuccessURL,
giropayCancelURL,
BanktxnPendingURL.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Transaction refused because of an
invalid argument. See additional
error messages for details.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

The transaction id is not valid

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid value for request billing
address parameter.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid item URL.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

OtherPaymentMethodType is
invalid.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

RegistrationDate of buyer is invalid.

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

209

API Error Codes
SetExpressCheckout API Errors

Error
Code

210

Short Message

Long Message

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay buyer feedback overall
positive count.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay buyer feedback overall
negative count.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay buyer feedback total
positive count.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay buyer feedback total
negative count.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay buyer feedback recent
positive count.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay buyer feedback recent
negative count.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

SellerRegistrationDate is invalid.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay seller feedback overall
positive count.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay seller feedback overall
negative count.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay seller feedback total
positive count.

August 2012

Correcting This Error...

Name-Value Pair API Developer Guide

API Error Codes
SetExpressCheckout API Errors

Error
Code

Short Message

Long Message

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay seller feedback total
negative count.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay seller feedback recent
positive count.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay seller feedback recent
negative count.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay item transaction date.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay item buyer protection
type.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid eBay item payment hold risk.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Multiple eBay order IDs not allowed.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

AllowPushFunding value specified is
invalid. It must be 0 or 1 or an empty
string.

10005

Option not supported.

Merchant not enabled to use
enhanced checkout data.

10005

Option not supported.

Merchant not enabled to use
OtherPaymentMethodDetails.

10005

Option not supported.

Transaction ID is not supported.

10007

Permission denied

You do not have permission to make
this API call

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

211

212

API Error Codes
SetExpressCheckout API Errors

Error
Code

Short Message

Long Message

10010

Invalid Invoice

Non-ASCII invoice id is not
supported.

10101

Option not supported.

Express Checkout temporarily
unavailable. Please try later.

10102

PaymentAction of Order
Temporarily Unavailable

PaymentAction of Order is
temporarily unavailable. Please try
later or use other PaymentAction.

10103

Please use another Solution
Type.

Your Solution Type is temporarily
unavailable. If possible, please use
another Solution Type.

10400

Transaction refused because
of an invalid argument. See
additional error messages for
details.

OrderTotal is missing.

10401

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Order total is invalid.

10402

Authorization only is not
allowed for merchant.

This merchant account is not
permitted to set PaymentAction to
Authorization. Please contact
Customer Service.

10404

Transaction refused because
of an invalid argument. See
additional error messages for
details.

ReturnURL is missing.

10405

Transaction refused because
of an invalid argument. See
additional error messages for
details.

CancelURL is missing.

10407

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Invalid buyer email address
(BuyerEmail).

10409

You’re not authorized to
access this info.

Express Checkout token was issued
for a merchant account other than
yours.

10410

Invalid token

Invalid token.

August 2012

Correcting This Error...

Name-Value Pair API Developer Guide

API Error Codes
SetExpressCheckout API Errors

Error
Code

Short Message

Long Message

Correcting This Error...

10411

This Express Checkout
session has expired.

This Express Checkout session has
expired. Token value is no longer
valid.

If you receive this error, you
must return your buyer to
PayPal to approve the use of
PayPal again. Display an error
message to inform the buyer
that the transaction expired,
and provide a button to return
to PayPal. In this situation, you
are effectively restarting the
entire checkout process. (Do
not reuse the expired token
value on
SetExpressCheckout
request.) However, because
you already know the final
OrderTotal, be sure to
update the value for that
element if appropriate. You
might also want to update the
values for ReturnURL and
CancelURL, if necessary.

10412

Duplicate invoice

Payment has already been made for
this InvoiceID.

PayPal checks that
InvoiceID values are unique
for any particular merchant. If
you send an InvoiceID value
already associated with another
transaction in the PayPal
system, PayPal returns error
code 10412.
You might not be able to
correct this error during an
actual checkout. If you receive
this error, research why it
might occur and modify your
implementation of Express
Checkout to ensure that you
generate unique invoice
identification numbers.

10413

Transaction refused because
of an invalid argument. See
additional error messages for
details

The totals of the cart item amounts
do not match order amounts.

If you receive this error, be
sure the total of the payment
detail item parameters, such as
ItemTotal, HandlingTotal,
TaxTotal, and so forth add up
to the order total.

Name-Value Pair API Developer Guide

August 2012

213

API Error Codes
SetExpressCheckout API Errors

Error
Code

214

Short Message

Long Message

Correcting This Error...

10415

Transaction refused because
of an invalid argument. See
additional error messages for
details.

A successful transaction has already
been completed for this token.

PayPal allows a token only
once for a successful
transaction.
If you determine that your
buyers are clicking your “Place
Order” button twice, PayPal
recommends that you disable
the button after your buyer has
clicked it.

10418

Transaction refused because
of an invalid argument. See
additional error messages for
details

The currencies of the shopping cart
amounts must be the same.

10425

Express Checkout has been
disabled for this merchant.

Express Checkout has been disabled
for this merchant. Please contact
Customer Service.

10426

Transaction refused because
of an invalid argument. See
additional error messages for
details

Item total is invalid.

10427

Transaction refused because
of an invalid argument. See
additional error messages for
details

Shipping total is invalid.

10428

Transaction refused because
of an invalid argument. See
additional error messages for
details

Handling total is invalid.

10429

Transaction refused because
of an invalid argument. See
additional error messages for
details

Tax total is invalid.

10430

Transaction refused because
of an invalid argument. See
additional error messages for
details

Item amount is missing.

10431

Transaction refused because
of an invalid argument. See
additional error messages for
details

Item amount is invalid.

August 2012

Name-Value Pair API Developer Guide

API Error Codes
SetExpressCheckout API Errors

Error
Code

Short Message

Long Message

10432

Transaction refused because
of an invalid argument. See
additional error messages for
details

Invoice ID value exceeds maximum
allowable length.

10433

Transaction refused because
of an invalid argument. See
additional error messages for
details

Value of Order Description has been
truncated.

10434

Transaction refused because
of an invalid argument. See
additional error messages for
details

Value of Custom element has been
truncated.

10436

Transaction refused because
of an invalid argument. See
additional error messages for
details.

PageStyle value exceeds maximum
allowable length.

10437

Transaction refused because
of an invalid argument. See
additional error messages for
details.

cpp-header-image value exceeds
maximum allowable length.

10438

Transaction refused because
of an invalid argument. See
additional error messages for
details.

cpp-header-image value exceeds
maximum allowable length.

10439

Transaction refused because
of an invalid argument. See
additional error messages for
details.

cpp-header-image value exceeds
maximum allowable length.

10440

Transaction refused because
of an invalid argument. See
additional error messages for
details.

cpp-header-image value exceeds
maximum allowable length.

10441

Transaction refused because
of an invalid argument. See
additional error messages for
details

The NotifyURL element value
exceeds maximum allowable length.

10442

ButtonSource value
truncated.

The ButtonSource element value
exceeds maximum allowable length.

10446

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Sale is only allowed PaymentAction.

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

215

API Error Codes
SetExpressCheckout API Errors

Error
Code

216

Short Message

Long Message

10457

Error occurred in
communicating to eBay

eBay API creation error

10458

Error occurred in
communicating to eBay

eBay API unknown failure

10459

Error occurred in
communicating to eBay

eBay API failure

10460

Error occurred in
communicating to eBay

Parsing error

10461

Error occurred in
communicating to eBay

Item number invalid, removed, or
unavailable

10462

Error occurred in
communicating to eBay

Order not found

10463

Error occurred in
communicating to eBay

eBay user password incorrect

10464

Error occurred in
communicating to eBay

Item ID and Transaction ID
mismatch

10465

Error occurred in
communicating to eBay

eBay user invalid

10467

Error occurred in
communicating to eBay

Duplicate Item ID

10468

Transaction refused because
of an invalid argument. See
additional error messages for
details

Duplicate Order ID

10469

PaymentAction of Order
Temporarily Unavailable

Express Auctions is unavailable

10470

Wowo flag is off for
ExpressO feature

Solution Type passed as Sole while
ExpressO feature is turned off

10471

Transaction refused because
of an invalid argument. See
additional error messages for
details

ReturnURL is missing

10472

Transaction refused because
of an invalid argument. See
additional error messages for
details

CancelURL is missing

10473

Error occurred in
communicating to eBay

Multiple Order IDs are not supported

August 2012

Correcting This Error...

Name-Value Pair API Developer Guide

API Error Codes
SetExpressCheckout API Errors

Error
Code

Short Message

Long Message

10474

Invalid Data

This transaction cannot be processed.
The country code in the shipping
address must match the buyer's
country of residence

10475

Transaction refused because
of an invalid argument. See
additional error messages for
details

This transaction cannot be completed
with PaymentAction of Sale

10476

Invalid Data

Maximum number of billing
agreements exceeded

10477

Invalid Data

More than one billing agreement
specified for reference transaction

10478

Invalid Data

Recurring payments profile
description must be provided if the
billing agreement type is recurring
payments

10479

Invalid Data

Billing agreement types cannot be
mixed in the same request

10480

Invalid Data

Invalid billing agreement type

10485

Payment not authorized

Payment has not been authorized by
the user.

10537

Risk Control Country Filter
Failure

The transaction was refused because
the country was prohibited as a result
of your Country Monitor Risk
Control Settings.

10538

Risk Control Max Amount
Failure

The transaction was refused because
the maximum amount was excceeded
as a result of your Maximum
Amount Risk Control Settings.

10539

Payment declined by your
Risk Controls settings:
PayPal Risk Model.

Payment declined by your Risk
Controls settings: PayPal Risk
Model.

10725

Shipping Address Country
Error

There was an error in the Shipping
Address Country field

10727

Shipping Address1 Empty

The field Shipping Address1 is
required

10728

Shipping Address City
Empty

The field Shipping Address City is
required

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

217

API Error Codes
SetExpressCheckout API Errors

Error
Code

218

Short Message

Long Message

10729

Shipping Address State
Empty

The field Shipping Address State is
required

10730

Shipping Address Postal
Code Empty

The field Shipping Address Postal
Code is required

10731

Shipping Address Country
Empty

The field Shipping Address Country
is required

10736

Shipping Address Invalid
City State Postal Code

A match of the Shipping Address
City, State, and Postal Code failed.

10800

Invalid Data

Your request is too long. Check
URLs and other long strings.

11001

Exceeds maximum length.

Value of NoteText element is
truncated.

11001

Exceeds maximum length.

OtherPaymentMethodID exceeds
maximum length.

11001

Exceeds maximum length.

OtherPaymentMethodLabel exceeds
maximum length.

11001

Exceeds maximum length.

OtherPaymentMethodLabelDescripti
on exceeds maximum length.

11001

Exceeds maximum length.

OtherPaymentMethodLongDescripti
on exceeds maximum length.

11001

Exceeds maximum length.

OtherPaymentMethodLongDescripti
onTitle exceeds maximum length.

11001

Exceeds maximum length.

OtherPaymentMethodIcon exceeds
maximum length.

11068

Seller restriction.

All sellers restricted.

11547

Recurring payments
temporarily unavailable; try
again later

Recurring payments temporarily
unavailable.

11547

Permission denied.

Permission Denied. You are not
authorized to do this kind of
transaction

11601

Request for billing address
failed

Billing address request is not enabled
for merchant

11602

Request for billing address
failed

Feature not yet available

11801

Invalid Data

You cannot pass both new and
deprecated parameter address fields.

August 2012

Correcting This Error...

Name-Value Pair API Developer Guide

API Error Codes
SetExpressCheckout API Errors

Error
Code

Short Message

Long Message

11802

Invalid Data

You cannot pass both the new and
deprecated Custom parameter.

11803

Invalid Data

You cannot pass both the new and
deprecated Invoice ID parameter.

11804

Invalid Data

You cannot pass both the new and
deprecated order description.

11805

Invalid Data

You cannot pass both the new and
deprecated order total or amount
parameters.

11806

Invalid Data

You cannot pass both the new and
deprecated
ProfileAddressChangeDate
parameter.

11807

Invalid Data

You cannot pass both the new and
deprecated ShippingMethod
parameter.

11810

Transaction refused because
of an invalid argument. See
additional error messages for
details

Invalid Insurance Amount.

11811

Transaction refused because
of an invalid argument. See
additional error messages for
details

Invalid Shipping Discount.

11812

Invalid Data

The value of Description parameter
has been truncated.

11813

Transaction refused because
of an invalid argument. See
additional error messages for
details

Invalid callback URL.

Callback URL is wrong type

Callback URL is wrong type; you
must use the HTTPS

11814

Invalid data

Invalid value for AllowNote.

11815

Transaction refused because
of an invalid argument. See
additional error messages for
details

Item sales tax is invalid.

Callback options missing

You must specify callback options
when you specify a callback URL

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

Ensure that your callback URL
starts with https://.

219

API Error Codes
SetExpressCheckout API Errors

Error
Code

220

Short Message

Long Message

Invalid callback timeout

The callback timeout is is zero; you
must specify a longer timeout

Line items missing

Line items are required when specify
a callback URL for flate rate
shipping options

Callback URL is too long

The callback URL must not exceed
1,024 characters

Multiple default shipping
options specified

You can only specify one default
shipping option at a time

No default shipping option
specified

You must specify a default shipping
option

Invalid shipping total

Invalid shipping total; it should equal
the shipping amount of the default
shipping option

Invalid shipping options

Invalid shipping options; you must
specify a name and amount for each
shipping option

11821

Invalid shipping options

Invalid shipping options; you must
specify a name and amount for each
shipping option type

11822

Multiple default shipping
options specified

More than one shipping option type
is marked as the default; you can
only specify one default shipping
option at a time

11823

No default shipping option
specified

You must specify one shipping
option type as the default

11824

Invalid callback timeout

The callback timeout is zero; you
must specify a longer timeout value

11825

Flat-rate shipping options
are missing

Flat-rate shipping options are
missing; you must specify flat-rate
shipping options when you specify a
callback URL

11826

Invalid shipping total

Invalid shipping total; it should equal
the shipping amount of the selected
shipping option

11827

Line items missing

Line items missing; line items are
required when you specify a callback
URL for flat-rate shipping options

August 2012

Correcting This Error...

Name-Value Pair API Developer Guide

API Error Codes
SetExpressCheckout API Errors

Error
Code

Short Message

Long Message

11828

Maximum amount of order
not specified

Maximum amount of order not
specified; you must specify the
estimated value of the order when
using a flat-rate shipping option

11829

Shipping total is missing

Shipping total is missing; you must
specify a shipping total when using a
flat-rate shipping option

11830

Insurance amount is missing

Insurance amount is missing; you
have offered insurance but have not
specified an amount.

11831

Callback URL is too long

Callback URL is too long; it must not
exceed 1,024 characters

11832

Maximum amount of order
Maximum amount of order is less
is less than itemized amounts than itemized amounts; the value of
all items, including handling,
shipping, tax, and insurance cannot
be greater than the maximum amount
of the order

12109

Option not supported.

Seller blocks payments via eBay
checkout for all eBay items.

12124

Option not supported.

Express Checkout not supported for
you.

12200

Buyer ID is not present.

Buyer ID must be specified to
process an Immediate Payment item.

12201

Immediate Payment item
was not found.

The item specified is either not valid
or is not currently available for
purchase as an Immediate Payment
item.

12202

More than one eBay item is
present.

Only one Immediate Payment item
can be paid for in a single PayPal
payment transaction.

12205

eBay Transaction ID and
eBay Order ID must be null.

Requests for eBay Immediate
Payment items should not contain
either eBay transaction ID or eBay
order ID. If the fields are present,
they should contain null values.

12207

Cart ID is required for
Immediate Payment item.

Cart ID is required for Immediate
Payment item.

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

Please check that the item is a
valid Immediate Payment item.

221

API Error Codes
SetExpressCheckout API Errors

Error
Code

222

Short Message

Long Message

12208

eBay item amount does not
match Express Checkout
API item amount.

eBay item amount must match
Express Checkout API item amount.

13100

Parallel payments
functionality is not available

Parallel payments functionality is not
available

13101

Invalid Data

Payment action of Order is only
supported for parallel payments

13102

Payment Request ID is
missing

Payment Request ID is mandatory
for parallel payments

13103

Duplicate Payment Request
ID passed

Payment Request ID must be unique
for parallel payments

13104

Transaction refused because
of an invalid argument. See
Additional error messages
for details.

Number of payment requests exceeds
maximum number of supported
requests.

13105

Invalid Data

Billing Agreement is not supported
for parallel payments.

13106

Invalid Data

You cannot pass both the new and
deprecated PaymentAction
parameter.

13108

Merchant is not eligible.

Merchant is not eligible for parallel
payments.

13110

Multi Payments Sale is Not
allowed

Due to some technical diffculties the
Multi Payments for Sale is not
avaliable now please try again later.

13111

Mixed Payment action not
supported

The Payment Action passed should
be unique, mixed Payment Action
not supported

13114

Buyer Didn't Complete

The Buyer returned without
completing the payment

13115

Seller ID Missing

Seller ID is mandatory for parallel
payments

13116

Transaction refused because
of an invalid argument. See
additional error messages for
details.

The transaction is in progress for this
token.

August 2012

Correcting This Error...

Name-Value Pair API Developer Guide

API Error Codes
GetExpressCheckoutDetails API Errors

GetExpressCheckoutDetails API Errors
GetExpressCheckoutDetails API Errors
Error
Code

Short Message

Long Message

10001

Internal Error

10001

Internal Error

Transaction failed due to internal error

10001

ButtonSource value
truncated.

The transaction could not be loaded

10001

ButtonSource value
truncated.

The transaction could not be loaded

10003

Missing argument.

OtherPaymentMethodID is missing.

10003

Missing argument.

OtherPaymentMethodLabel is missing.

10003

Missing argument.

OtherPaymentMethodType is missing.

10003

Missing argument.

One or more of these giropay URLs is
missing: giropaySuccessURL,
giropayCancelURL,
BanktxnPendingURL.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Transaction refused because of an
invalid argument. See additional error
messages for details.

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

The transaction id is not valid

10004

Invalid transaction type

You can not get the details for this type
of transaction

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

The transaction could not be loaded

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

The transaction id is not valid

10007

Permission denied

You do not have permission to make
this API call

10007

Permission denied

You do not have permission to get the
details of this transaction

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

223

API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code

Short Message

Long Message

10007

Permission denied

You do not have permission to make
this API call

10408

Express Checkout token is
missing.

Express Checkout token is missing.

10409

You’re not authorized to
access this info.

Express Checkout token was issued for
a merchant account other than yours.

10410

Invalid token

Invalid token.

10411

This Express Checkout
session has expired.

This Express Checkout session has
expired. Token value is no longer valid.

13112

Cannot Pay Seller.

The Buyer will not be able to Pay the
seller for this transaction

13116

Transaction refused because
of an invalid argument. See
additional error messages for
details.

The transaction is in progress for this
token.

Correcting This Error...

DoExpressCheckoutPayment API Errors
DoExpressCheckoutPayment API Errors

224

Error
Code

Short Message

Long Message

10001

Internal Error

Transaction failed due to
internal error

10001

Internal Error

Warning an internal error has
occurred. The transaction id
may not be correct

10001

ButtonSource value
truncated.

The transaction could not be
loaded

10001

Internal Error

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Transaction refused because of
an invalid argument. See
additional error messages for
details.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The transaction id is not valid

August 2012

Correcting This Error...

Name-Value Pair API Developer Guide

API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code

Short Message

Long Message

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid item URL.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

SellerRegistrationDate is
invalid.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid eBay seller feedback
overall positive count.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid eBay seller feedback
overall negative count.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid eBay seller feedback
total positive count.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid eBay seller feedback
total negative count.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid eBay seller feedback
recent positive count.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid eBay seller feedback
recent negative count.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid eBay item transaction
date.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid eBay item buyer
protection type.

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

225

API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code

226

Short Message

Long Message

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid eBay item payment
hold risk.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Multiple eBay order IDs not
allowed.

10007

Permission denied

You do not have permissions to
make this API call

10406

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The PayerID value is invalid.

10408

Express Checkout token is
missing.

10409

You’re not authorized to
access this info.

Express Checkout token was
issued for a merchant account
other than yours.

10410

Invalid token

Invalid token.

10411

This Express Checkout
session has expired.

This Express Checkout session
has expired. Token value is no
longer valid.

10412

Duplicate invoice

Payment has already been
made for this InvoiceID.

10413

Transaction refused
because of an invalid
argument. See additional
error messages for details

The totals of the cart item
amounts do not match order
amounts.

10414

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The amount exceeds the
maximum amount for a single
transaction.

10415

Transaction refused
because of an invalid
argument. See additional
error messages for details.

A successful transaction has
already been completed for this
token.

August 2012

Correcting This Error...

If you receive this error, be sure the
total of the payment detail item
parameters, such as ItemTotal,
HandlingTotal, TaxTotal, and so forth
add up to the order total.

Name-Value Pair API Developer Guide

API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code

Short Message

Long Message

10416

Transaction refused
because of an invalid
argument. See additional
error messages for details.

You have exceeded the
maximum number of payment
attempts for this token.

10417

Transaction cannot
complete.

The transaction cannot
complete successfully. Instruct
the customer to use an
alternative payment method.

10418

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The currencies of the shopping
cart amounts must be the same.

10419

Express Checkout
PayerID is missing.

Express Checkout PayerID is
missing.

10420

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Express Checkout
PaymentAction is missing.

10421

This Express Checkout
session belongs to a
different customer.

This Express Checkout session
belongs to a different customer.
Token value mismatch.

10422

Customer must choose
new funding sources.

The customer must return to
PayPal to select new funding
sources.

10424

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Shipping address is invalid.

10426

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Item total is invalid.

10427

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Shipping total is invalid.

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

Instruct the buyer that PayPal is unable
to process the payment and redisplay
alternative payment methods with
which the buyer can pay.

Verify that your programs are properly
associating the Tokens and PayerIDs.

If you receive this error message,
PayPal recommends that you return
your buyer to PayPal to review and
approve new valid funding sources.
Although this error is rare, you should
consider trapping the error to display a
message to the buyer describing what
happened, along with a button or
hyperlink to return to PayPal.

227

API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code

228

Short Message

Long Message

10428

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Handling total is invalid.

10429

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Tax total is invalid.

10431

Item amount is invalid.

10432

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invoice ID value exceeds
maximum allowable length.

10433

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Value of OrderDescription
element has been truncated.

10434

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Value of Custom element has
been truncated.

10435

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The customer has not yet
confirmed payment for this
Express Checkout session.

10441

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The NotifyURL element value
exceeds maximum allowable
length.

10442

ButtonSource value
truncated.

The ButtonSource element
value exceeds maximum
allowable length.

10443

Transaction refused
because of an invalid
argument. See additional
error messages for details.

This transaction cannot be
completed with
PaymentAction of Order.

10444

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The transaction currency
specified must be the same as
previously specified.

August 2012

Correcting This Error...

Name-Value Pair API Developer Guide

API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code

Short Message

Long Message

10445

This transaction cannot be
processed at this time.
Please try again later.

This transaction cannot be
processed at this time. Please
try again later.

10446

Unconfirmed email

A confirmed email is required
to make this API call.

10474

Invalid Data

This transaction cannot be
processed. The country code in
the shipping address must
match the buyer’s country of
residence.

10481

Transaction refused
because of an invalid
argument. See additional
error messages for details.

PaymentAction of
Authorization is not allowed
with Unilateral and NonCredentialed authentication.

10486

This transaction couldn't
be completed.

This transaction couldn't be
completed. Please redirect your
customer to PayPal.

10482

Transaction refused
because of an invalid
argument. See additional
error messages for details.

PaymentAction of Order is not
allowed with Unilateral and
Non-Credentialed
authentication.

10537

Risk Control Country
Filter Failure

The transaction was refused
because the country was
prohibited as a result of your
Country Monitor Risk Control
Settings.

10538

Risk Control Max Amount
Failure

The transaction was refused
because the maximum amount
was excceeded as a result of
your Maximum Amount Risk
Control Settings.

10539

Payment declined by your
Risk Controls settings:
PayPal Risk Model.

Payment declined by your Risk
Controls settings: PayPal Risk
Model.

10725

Shipping Address Country
Error

There was an error in the
Shipping Address Country
field

10727

Shipping Address1 Empty

The field Shipping Address1 is
required

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

The buyer selects the country of
residence when they sign up for their
PayPal account. The country of
residence displays after the dash in the
title on the Account Overview page.

Redirect the buyer back to PayPal using
the original token so that the customer
can use or add a new funding
instrument.

229

API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code

230

Short Message

Long Message

10728

Shipping Address City
Empty

The field Shipping Address
City is required

10729

Shipping Address State
Empty

The field Shipping Address
State is required

10730

Shipping Address Postal
Code Empty

The field Shipping Address
Postal Code is required

10731

Shipping Address Country
Empty

The field Shipping Address
Country is required

10736

Shipping Address Invalid
City State Postal Code

A match of the Shipping
Address City, State, and Postal
Code failed.

11001

Exceeds maximum length.

Value of NoteText element is
truncated.

11610

Payment Pending your
review in Fraud
Management Filters

Payment Pending your review
in Fraud Management Filters

11611

Transaction blocked by
your settings in FMF

Transaction blocked by your
settings in FMF

11612

Could not process your
request to accept/deny the
transaction

Could not process your request
to accept/deny the transaction

11820

Transaction refused
because of an invalid
argument. See additional
error messages for details

Invalid Order URL.

Invalid shipping amount

Invalid shipping amount; it
should equal the shipping
amount of the selected
shipping option

Invalid shipping options

Invalid shipping options; you
must specify a name and
amount for each shipping
option

11821

Invalid shipping options

Invalid shipping options; you
must specify a name and
amount for each shipping
option type

11826

Invalid shipping total

Invalid shipping total; it should
equal the shipping amount of
the selected shipping option

August 2012

Correcting This Error...

Name-Value Pair API Developer Guide

API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code

Short Message

Long Message

12125

PP incentive no longer
available.

There's a problem with the
redemption code(s) you
entered and can't be used at this
time. Your payment has not
been processed. Please go back
to PayPal so that the code(s)
can be removed, your order
total can be updated and then
you'll be able to complete
checkout.

12126

Payment could not be
processed at this time.
Incentive temporarily
unavailable.

We're having problems
processing redemption codes at
this time. Your payment has
not been processed. You can
try to check out again at a later
time or complete your payment
without the discount applied.

12201

Immediate Payment item
was not found.

The item specified is either not
valid or is not currently
available for purchase as an
Immediate Payment item.

12203

Payment rolled back
because of pending item.

Payment was not created
because it would have been in a
pending state, which is
unacceptable for Immediate
Payment items.

12204

Transaction reversed.

Error occurred causing
transaction reversal.

12206

The value of
PaymentAction must be
Sale for Immediate
Payment item.

Order and Authorization are
not acceptable values for
PaymentAction when the item
is an Immediate Payment

12207

Cart ID is required for
Immediate Payment item.

12208

eBay item amount does
not match Express
Checkout API item
amount.

eBay item amount does not
match Express Checkout API
item amount.

13100

Parallel payments
functionality is not
available

Parallel payments functionality
is not available

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

Please check that the item is a valid
Immediate Payment item.

231

232

API Error Codes
DoExpressCheckoutPayment API Errors

Error
Code

Short Message

Long Message

13101

Invalid Data

Payment action of Order is
only supported for parallel
payments

13102

Payment Request ID is
missing

Payment Request ID is
mandatory for parallel
payments

13103

Duplicate Payment
Request ID passed

Payment Request ID must be
unique for parallel payments

13104

Transaction refused
because of an invalid
argument. See Additional
error messages for details.

Number of payment requests
exceeds maximum number of
supported requests.

13106

Invalid Data

You cannot pass both the new
and deprecated PaymentAction
parameter.

13107

Parallel payments partially
successful.

One or more payment requests
failed. Check individual
payment responses for more
information.

13110

Multi Payments Sale is
Not allowed

Due to some technical
diffculties the Multi Payments
for Sale is not avaliable now
please try again later.

13111

Mixed Payment action not
supported

The Payment Action passed
should be unique, mixed
Payment Action not supported

13113

Buyer Cannot Pay.

The Buyer cannot pay with
PayPal for this transaction.

13115

Seller ID Missing

Seller ID is mandatory for
parallel payments

13116

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The transaction is in progress
for this token.

13751

Could not retrieve the
original successful
response.

Transaction completed
successfully, but could not
retrieve the original successful
response.

August 2012

Correcting This Error...

Name-Value Pair API Developer Guide

API Error Codes
Authorization and Capture API Errors

Authorization and Capture API Errors
Authorization and Capture API Error Messages
Error
Code

Short
Message

Long Message

10001

Internal Error

10001

Internal Error

Transaction failed due to
internal error

10004

Internal Error

Invalid argument

10007

Permission
denied

You do not have
permissions to make this
API call

10009

Transaction
refused

Account is locked or
inactive

10010

Transaction
refused because
of an invalid
argument. See
additional error
messages for
details.

Invalid argument

10202

Exceed max

Transaction would
exceed user’s monthly
maximum

DoAuthorization
DoCapture

10600

Authorization
voided.

Authorization is voided.

DoAuthorization
DoCapture
DoReauthorization
DoVoid

Close the order or
authorization.

10601

Authorization
expired.

Authorization has
expired.

DoAuthorization
DoCapture
DoReauthorization
DoVoid

Close the order or
authorization.

10602

Authorization
completed.

Authorization has already
been completed.

DoAuthorization
DoCapture
DoReauthorization
DoVoid

Close the order or
authorization.

10603

The buyer is
restricted.

The buyer account is
restricted.

DoAuthorization
DoCapture
DoReauthorization
DoVoid

Contact the buyer.

Name-Value Pair API Developer Guide

Returned By API
Call...

Correcting This
Error...

Retry the request at a
later time or close order.

August 2012

233

234

API Error Codes
Authorization and Capture API Errors

Error
Code

Short
Message

Returned By API
Call...

Correcting This
Error...

10604

Authorization
must include
both buyer and
seller.

Authorization transaction
cannot be unilateral. It
must include both buyer
and seller to make an
auth.

DoAuthorization

Review the order to
ensure customer and
seller are both PayPal
members.

10605

Unsupported
currency.

Currency is not
supported.

DoAuthorization
DoCapture

Retry the request with a
PayPal-supported
currency.

10606

Buyer cannot
pay.

Transaction rejected,
please contact the buyer.

DoAuthorization
DoCapture
DoReauthorization

Contact the buyer.

10607

Auth&Capture
unavailable.

Authorization & Capture
feature unavailable.

DoAuthorization
DoCapture
DoReauthorization
DoVoid

Contact PayPal Customer
Service.

10608

Funding source
missing.

The funding source is
missing.

DoAuthorization
DoCapture
DoReauthorization

Contact the buyer.

10609

Invalid
transactionID.

Transaction id is invalid.

DoAuthorization
DoCapture
DoReauthorization
DoVoid

Check the validity of the
authorization ID and
reattempt the request.

10610

Amount limit
exceeded.

Amount specified
exceeds allowable limit.

DoAuthorization
DoCapture
DoReauthorization

Reattempt the request
with a lower amount.

10611

Not enabled.

Authorization & Capture
feature is not enabled for
the merchant. Contact
customer service.

DoAuthorization
DoCapture
DoReauthorization

Contact PayPal Customer
Service.

10612

No more
settlement.

Maxmimum number of
allowable settlements has
been reached. No more
settlement for the
authorization.

DoCapture

Close the order.

10613

Currency
mismatch.

Currency of capture must
be the same as currency
of authorization.

DoCapture

Ensure that the currencies
are the same, and retry
the request.

10614

Cannot void
reauth.

You can void only the
original authorization,
not a reauthorization.

DoVoid

Void the authorization.

Long Message

August 2012

Name-Value Pair API Developer Guide

API Error Codes
Authorization and Capture API Errors

Error
Code

Short
Message

Returned By API
Call...

Correcting This
Error...

10615

Cannot reauth
reauth.

You can reauthorize only
the original authorization,
not a reauthorization.

DoReauthorization

Capture the
reauthorization.

10616

Maximum
number of
reauthorization
allowed for the
auth is reached.

Maximum number of
reauthorization allowed
for the auth is reached.

DoReauthorization

Capture or close the
authorization.

10617

Reauthorization
not allowed.

Reauthorization is not
allowed inside honor
period.

DoReauthorization

Capture the authorization
or reauthorize outside of
honor period.

10618

Transaction
already voided
or expired.

Transaction has already
been voided or expired.

DoAuthorization
DoCapture
DoReauthorization
DoVoid

Close the order or
authorization.

10619

Invoice ID value
exceeds
maximum
allowable
length.

Invoice ID value exceeds
maximum allowable
length.

DoCapture

Check the length of the
invoice ID and reattempt
the request.

10620

Order has
already been
voided, expired,
or completed.

Order has already been
voided, expired, or
completed.

DoAuthorization
DoCapture
DoVoid

Close this order.

10621

Order has
expired.

Order has expired.

DoAuthorization
DoCapture
DoVoid

Close this order.

10622

Order is voided.

DoAuthorization
DoCapture
DoVoid

Close this order.

10623

Maximum
number of
authorization
allowed for the
order is reached.

Maximum number of
authorization allowed for
the order is reached.

DoAuthorization
DoCapture
DoReauthorization
DoVoid

Capture this order.

10624

Duplicate
invoice

Payment has already
been made for this
Invoice ID.

DoAuthorization

Review the invoice ID
and reattempt the request.

Name-Value Pair API Developer Guide

Long Message

August 2012

235

236

API Error Codes
Authorization and Capture API Errors

Error
Code

Short
Message

Long Message

Returned By API
Call...

Correcting This
Error...

10625

Transaction
refused because
of an invalid
argument. See
additional error
messages for
details.

The amount exceeds the
maximum amount for a
single transaction.

DoAuthorization
DoCapture
DoReauthorization

Reattempt the request
with a lower amount.

10626

Risk

Transaction refused due
to risk model.

DoAuthorization
DoCapture
DoReauthorization

Contact the buyer.

10627

Transaction
refused because
of an invalid
argument. See
additional error
messages for
details.

The invoice ID field is
not supported for basic
authorizations.

DoAuthorization
DoReauthorization
DoVoid

The Invoice ID field can
be used only with
DoCapture.

10628

This transaction
cannot be
processed at this
time. Please try
again later.

This transaction cannot
be processed at this time.
Please try again later.

DoAuthorization
DoCapture
DoReauthorization
DoVoid

Retry the request at a
later time.

10629

Reauthorization
not allowed.

Reauthorization is not
allowed for this type of
authorization.

DoReauthorization

Use DoAuthorization to
authorize the order.

10630

Item amount is
invalid.

Item amount is invalid.

DoAuthorization
DoCapture

Check the item amount to
ensure that it is not zero
or negative.

10631

Processor
Warning.

The authorization is
being processed.

DoAuthorization

11094

This
authorization
cannot be
voided,
reauthorized, or
captured against.

This authorization can
only be handled through
the marketplace which
created it. It cannot
directly be voided,
reauthorized, or captured
against.

13122

Transaction
refused.

Transaction violates
PayPal use

DoCapture

August 2012

Name-Value Pair API Developer Guide

API Error Codes
GetTransactionDetails API Errors

GetTransactionDetails API Errors
GetTransactionDetails API Errors
Error Code

Short Message

Long Message

10001

Internal Error

10004

Transaction refused because of an
invalid argument. See additional
error messages for details.

Store ID is required if Terminal ID is specified.

TransactionSearch API Errors
TransactionSearch API Errors
Error
Code

Short Message

Long Message

10001

Internal Error

10001

ButtonSource value
truncated.

The transaction could not be loaded

10003

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Start date is a required parameter

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Start date is invalid

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

End date is invalid

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Currency is not supported

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Transaction class is not supported

Name-Value Pair API Developer Guide

August 2012

237

API Error Codes
TransactionSearch API Errors

Error
Code

238

Short Message

Long Message

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Receipt id is not valid

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Payer email is invalid

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Auction item id is not valid

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Receiver email is invalid

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

You can not search for a transaction id and a receipt id

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

Receiver can only be specified for payments you’ve received

10004

Transaction refused because
of an invalid argument. See
additional error messages for
details.

The transaction id is not valid

10007

Permission denied

You do not have permission to search for this transaction

10007

Permission denied

You do not have permission to make this API call

11002

Search warning

The number of results were truncated. Please change your search
parameters if you wish to see all your results.

August 2012

Name-Value Pair API Developer Guide

API Error Codes
RefundTransaction API Errors

RefundTransaction API Errors
RefundTransaction API Errors
Error
Code

Short Message

Long Message

10001

Internal Error

10001

Internal Error

Warning an internal error has occurred.
The transaction id may not be correct

10001

Internal Error

The transaction could not be loaded.

10002

Restricted account

Account is restricted.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The partial refund amount must be a
positive amount

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

You can not specify a partial amount
with a full refund

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

A transaction id is required

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The transaction id is not valid

10007

Permission denied

You do not have permission to refund
this transaction

10007

Permission denied

You do not have permissions to make
this API call

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

239

API Error Codes
RefundTransaction API Errors

Error
Code

Short Message

Long Message

Correcting This Error...

10009

Transaction refused

You do not have a verified ACH

This error can be caused by
insufficient funds in your
PayPal balance to cover the
amount of the refund and either
of the following:
 Not having yet verified the
bank account associated
with your PayPal account
 Not having any bank
account associated with
your PayPal account
Be sure that you have sufficient
funds in your PayPal balance
and that you have verified the
associated bank account.

240

10009

Transaction refused

The partial refund amount must be less
than or equal to the original transaction
amount

10009

Transaction refused

The partial refund amount must be less
than or equal to the remaining amount

10009

Transaction refused

The partial refund amount is not valid

10009

Transaction refused

Because a complaint case exists on this
transaction, only a refund of the full or
full remaining amount of the
transaction can be issued

10009

Transaction refused

You are over the time limit to perform a
refund on this transaction

10009

Transaction refused

Can not do a full refund after a partial
refund

10009

Transaction refused

Account is locked or inactive

10009

Transaction refused

The partial refund must be the same
currency as the original transaction

10009

Transaction refused

This transaction has already been fully
refunded

10009

Transaction refused

Account is restricted

10009

Transaction refused

You can not refund this type of
transaction

10009

Transaction refused

You can not do a partial refund on this
transaction

August 2012

Name-Value Pair API Developer Guide

API Error Codes
RefundTransaction API Errors

Error
Code

Short Message

Long Message

10009

Transaction refused

The account for the counterparty is
locked or inactive

10009

Transaction refused

This transaction already has a
chargeback filed

10009

Transaction refused

You have not filled out the Direct Debit
Instruction

10011

Invalid transaction id value

Transaction refused because of an
invalid transaction id value

10755

Unsupported currency

Currency is not supported

11603

Conflict with prior request
with same Message
Submission ID.

One or more critical fields in the
request conflict with prior message
with the same Message Submission ID
(specified in MSGSUBID parameter).

11604

Request for Message
Submission ID already in
progress.

Request for the specified Message
Submission ID (specified in
MSGSUBID parameter) cannot be
started until the previous request
finishes.

Retry the request at a later
time.

11607

Duplicate request for
specified Message
Submission ID.

The specified Message Submission ID
(specified in MSGSUBID parameter) is
a duplicate; result parameters of the
original request are attached.

Retry the request at a later
time.

11996

Use Adaptive Payment
Refund API

To do a refund on an Adaptive Payment
transaction, please use the Adaptive
Payment Refund API

12302

Dispute Refund Not
Allowed

This transaction already has a PayPal
dispute filed

13513

Duplicate request for
specified Invoice ID.

The specified Invoice ID is a duplicate.

13531

Funding source provided
for this operation is not
supported

The funding source provided for this
operation is not supported. Please
provide a valid value.

13601

Refund cannot exceed the
transaction amount.

Refunds to users without PayPal
accounts cannot exceed the transaction
amount.

13602

Insufficient funds

Refund failed due to insufficient funds
in your PayPal account

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

241

API Error Codes
MassPay API Errors

MassPay API Errors
MassPay API Errors

242

Error
Code

Short Message

Long Message

10001

Invalid account number.

The transaction failed as a result of an invalid credit card number.
Check the number or attempt with another card.

10001

Internal Error

10001

Internal Error

The transaction could not be loaded

10001

ButtonSource value truncated.

The transaction could not be loaded

10001

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The masspay receiver_type is not a recognizable type

10002

Account locked

The user account is locked

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The number of input records is greater than maximum allowed

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The number of input records is less than or equal to zero

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The note string length exceeds the maximum limit of 4000
characters

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The amount is missing

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The currency is missing

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

Currency is not supported

August 2012

Name-Value Pair API Developer Guide

API Error Codes
MassPay API Errors

Error
Code

Short Message

Long Message

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The amount is not a valid number

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The amount exceeds the max limit of a single mass pay item
~1

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The amount is less than or equal to zero

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The unique id string length exceeds the maximum limit of 30
characters

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The unique id string contains a space as a character

10004

Transaction refused because of
an invalid argument. See
additional error messages for
details.

The transaction id is not valid

10007

Permission denied

You do not have permissions to make this API call

10301

User not allowed

The user is not allowed to send money through Mass Pay

10303

Restricted account

Account is restricted

10304

Unconfirmed email

The user account has unconfirmed email

10305

Limit Exceeded

The user account needs to have its sending limit removed in order to
make a mass payment.

10306

Limit Exceeded

The user’s international account needs to have its sending limit
removed in order to make a mass payment

10307

Receive only account

The user account is receive only and therefore cannot send payments
out

10308

Masspay server configuration
error

There is some configuration error

10309

Masspay server unavailable

The mass pay server is unavailable

10310

Unable to create payment

Unable to create payments for masspay

Name-Value Pair API Developer Guide

August 2012

243

API Error Codes
Recurring Payments Errors

Error
Code

Short Message

Long Message

10311

Unable to submit payment

Unable to submit payments for masspay

10312

Masspay server error

The masspay server has reported errors

10313

Masspay Invalid Data

The masspay input file includes invalid data

10314

Masspay input parse error

The input to the masspay server is incorrect. Please make sure that
you are using a correctly formatted input.

10317

Masspay Invalid Email

The masspay input file includes invalid Email

10320

Internal Error

10321

Insufficient funds

The account does not have sufficient funds to do this masspay

10327

Masspay Invalid UserID

The masspay input file includes invalid UserID

Recurring Payments Errors
The following table lists errors for the following APIs that handle recurring payments profiles:


CreateRecurringPaymentsProfile



GetRecurringPaymentsProfileDetails



ManageRecurringPaymentsProfileStatus



UpdateRecurringPaymentsProfile



BillOutstandingAmount

Recurring Payments Errors

244

Error
Code

Short Message

Long Message

10001

Invalid account number

The transaction failed as a result of
invalid credit card number. Check
the number or attempt with another
credit card.

10003

Missing argument

Item name, amount and quantity
are required if item category is
provided.

Scenario: Merchant passes item
category as either Digital or
Physical but does not also pass
one of the following parameters:
name, amount, or quantity.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

You are not signed up to accept
payment for digitally delivered
goods.

Scenario: Merchant is not signed
up for digital goods but passes
item category as Digital.

August 2012

Additional Information

Name-Value Pair API Developer Guide

API Error Codes
Recurring Payments Errors

Error
Code

Short Message

Long Message

Additional Information

10004

Cart item calculation
mismatch.

Cart item calculation mismatch.
The regular non-trial billing period
amount is different than the sum of
the amounts for each item in the
cart.

Scenario: When the regular nontrial billing period amount is
different than the sum of the
amounts for each item in the
cart.

10004

Tax calculation mismatch.

Tax calculation mismatch. The tax
amount for the regular non-trial
billing period is different than the
sum of the tax for each item in the
cart.

Scenario: When the tax for the
regular non-trial billing period is
different than the sum of the tax
for each item in the cart.

10478

Invalid Data

Recurring payments profile
description must be provided if the
billing agreement type is recurring
payments.

10501

Invalid Configuration

This transaction cannot be
processed due to an invalid
merchant configuration.

Occurs when the billing
agreement is disabled or
inactive.

10502

Invalid Data

This transaction cannot be
processed. Please use a valid credit
card.

The credit card used is expired.

10504

Invalid Data

This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.

The CVV provided is invalid.
The CVV is between 3-4 digits
long.

10505

Gateway Decline

This transaction cannot be
processed.

The transaction was refused
because the AVS response
returned the value of N, and the
merchant account is not able to
accept such transactions.

10507

Invalid Configuration

This transaction cannot be
processed. Please contact PayPal
Customer Service.

Your PayPal account is
restricted. Contact PayPal for
more information.

10508

Invalid Data

This transaction cannot be
processed. Please enter a valid
credit card expiration date.

The expiration date must be a
two-digit month and four-digit
year.

10509

Invalid Data

This transaction cannot be
processed.

You must submit an IP address
of the buyer with each API call.

10510

Invalid Data

The credit card type is not
supported. Try another card type.

The credit card type entered is
not currently supported by
PayPal.

Name-Value Pair API Developer Guide

August 2012

245

246

API Error Codes
Recurring Payments Errors

Error
Code

Short Message

Long Message

Additional Information

10511

Invalid Data

This transaction cannot be
processed.

The merchant selected an value
for the PaymentAction field that
is not supported.

10512

Invalid Data

This transaction cannot be
processed. Please enter a first
name.

The first name of the buyer is
required for this merchant.

10513

Invalid Data

This transaction cannot be
processed. Please enter a last
name.

The last name of the buyer is
required for this merchant.

10535

Gateway decline

This transaction cannot be
processed. Please enter a valid
credit card number and type.

10548

Invalid Configuration

This transaction cannot be
processed. The merchant’s account
is not able to process transactions.

The merchant account
attempting the transaction is not
a business account at PayPal.
Check your account settings.

10550

Invalid Configuration

This transaction cannot be
processed.

Access to Direct Payment was
disabled for your account.
Contact PayPal for more
information.

10561

Invalid Data

There’s an error with this
transaction. Please enter complete
billing address.

10565

Merchant country
unsupported

The merchant country is not
supported.

10709

Invalid Data

There’s an error with this
transaction. Please enter an
address1 in the billing address.

There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.

10710

Invalid Data

There’s an error with this
transaction. Please enter a city in
the billing address.

There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.

10711

Invalid Data

There’s an error with this
transaction. Please enter your state
in the billing address.

There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.

10712

Invalid Data

There’s an error with this
transaction. Please enter your five
digit postal code in the billing
address.

There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.

August 2012

Name-Value Pair API Developer Guide

API Error Codes
Recurring Payments Errors

Error
Code

Short Message

Long Message

Additional Information

10713

Invalid Data

There’s an error with this
transaction. Please enter a country
in the billing address.

There was a problem with a
particular field in the address.
The long error message tells you
which field is invalid.

10744

Invalid Data

This transaction cannot be
processed. Please enter a valid
country code in the billing address.

There was a problem with a
particular field in the address.
The long error message will tells
you which field is invalid.

10748

Invalid Data

This transaction cannot be
processed without a Credit Card
Verification Number.

The merchant’s configuration
requires a CVV to be entered,
but no CVV was provided with
this transaction. Contact PayPal
if you wish to change this
setting.

10751

Invalid Data

There’s an error with this
transaction. Please enter a valid
state in the billing address.

The merchant provided an
address either in the United
States or Canada, but the state
provided is not a valid state in
either country.

10752

Gateway Decline

This transaction cannot be
processed.

The transaction was declined by
the issuing bank, not PayPal. The
merchant should attempt another
card.

10760

Invalid Configuration

This transaction cannot be
processed. The country listed for
your business address is not
currently supported.

The merchant’s country of
residence listed in their PayPal
account is not currently
supported to allow Direct
Payment transactions.

11089

Transaction Refused.

Account is locked or inactive.

11501

Invalid merchant country

The merchant’s country is
currently not supported

Missing token

11502

The token is missing or is
invalid

The token is missing or is invalid

One or more subscription detail
fields are missing from the
request.

11503

Missing subscription details

One or more schedule detail
fields are missing from the
request.

11504

Missing schedule details

11505

Start date should be greater
than current date

Subscription start date should be
greater than current date

Name-Value Pair API Developer Guide

August 2012

247

API Error Codes
Recurring Payments Errors

Error
Code

248

Short Message

Long Message

11506

Invalid max failed
payments

Max failed payments, if supplied,
must be >= 0

11507

Invalid trial amount

Trial amount must be >= 0

11508

Invalid trial total billing
cycles

Trial total billing cycles must be >
0

11509

Invalid trial billing period

Trial billing period must be one of
Day, Week, Month, SemiMonth, or
Year

11510

Invalid trial amount

Trial amount must be >= 0

11511

Invalid currency for trial
amount

This currency is currently not
supported for trial amount.

Currency must be USD.

11512

Invalid trial shipping
amount

Trial shipping amount must be >=
0

If a trial shipping amount is
supplied, it must be >= 0.

11513

Invalid currency for trial
shipping amount

This currency is currently not
supported for trial shipping amount

Currency must be USD.

11514

Invalid profile status

The profile status is invalid.

11515

Invalid currency for trial tax
amount

This currency is currently not
supported for trial tax amount

Currency must be USD.

11516

Invalid billing frequency

Billing Frequency must be > 0 and
be less than or equal to one year

The combination of billing
frequency and billing period
cannot exceed one year.

11517

Invalid total billing cycles

Total billing cycles must be >= 0 (0
means continuous)

11518

Invalid billing period

Billing period must be one of Day,
Week, Month, SemiMonth, or Year

11519

Invalid amount

Bill amount must be greater than 0

11520

Invalid currency for amount

This currency is currently not
supported for amount

11521

Invalid shipping amount

Shipping amount must be >= 0

11522

Invalid currency for
shipping amount

This currency is currently not
supported for shipping amount

11523

Invalid tax amount

Tax amount must be >= 0

11524

Invalid currency for tax
amount

This currency is currently not
supported for tax amount

11531

Invalid profile status

The profile status must be one of
(A)ctive, (C)ancelled, or e(X)pired

August 2012

Additional Information

Currency must be USD.

Name-Value Pair API Developer Guide

API Error Codes
Recurring Payments Errors

Error
Code

Short Message

Long Message

11543

Invalid payer country

The payer’s country is currently
not supported

11544

Invalid period status

The trial period status must be one
of (A)ctive or (C)ancelled

11545

Denied

Payer’s account is denied

11546

Denied

Merchant account is denied

11547

This feature is not available
at this time

Recurring payments feature is not
currently available; try again later

11548

Invalid currency code

Invalid currency code, all currency
codes much match

11549

Start Date is required

Subscription start date is required

11550

Start Date should be valid

Subscription start date should be
valid

11551

Profile ID is missing from
the request

Profile ID is missing from the
request

11552

Invalid profile ID

The profile ID is invalid

11553

Invalid action value
provided

Invalid action value provided

11554

Note is missing from the
request

Note is missing from the request

11556

Invalid profile status for
cancel action; profile
should be active or
suspended

Invalid profile status for suspend
action; profile should be active

11557

Invalid profile status for
suspend action; profile
should be active

Invalid profile status for reactivate
action; profile should be suspended

11558

Invalid profile status for
reactivate action; profile
should be suspended

The activation type is invalid

11560

Invalid activation type

The activation type is invalid

11561

Invalid initial amount

The initial amount is invalid

11562

Invalid auto bill type

The auto bill type is invalid

Additional Information

11555

Name-Value Pair API Developer Guide

August 2012

249

API Error Codes
Recurring Payments Errors

Error
Code

250

Short Message

Long Message

11564

The number of failed
payments should be greater
than the current number of
failed payments

The number of failed payments
should be greater than the current
number of failed payments

11567

The time of the update is
too close to the billing date

The time of the update is too close
to the billing date

11568

Invalid currency for
delinquent amount

Invalid currency for delinquent
amount

11569

Cannot increase delinquent
amount

Cannot increase delinquent amount

11570

The maximum number of
failed payments should be
greater than the current
number of failed payments

The maximum number of failed
payments should be greater than
the current number of failed
payments

11571

The total amount cannot
exceed 120% increment per
180 days

The total amount cannot exceed
120% increment per 180 days

11576

Bill amount is greater than
outstanding balance

11577

Another outstanding
payment is scheduled

Another outstanding payment is
scheduled

11578

Bill outstanding amount not
processed because of
scheduled payment

Recurring payment scheduled
within 24 hours, so we are not
processing the bill outstanding
amount

11579

Payment is failing

11581

Invalid Data

Profile description is invalid.

11582

No payment in queue

No scheduled payment has been
found.

11583

DPRP feature is unavailable

11584

Inactive profile

Profile is not active

11585

Missing Token or buyer
credit card

Missing token or payment source

11586

DPRP is disabled

DPRP is disabled for this
merchant.

11587

Billing Address is Partial

August 2012

Additional Information

Name-Value Pair API Developer Guide

API Error Codes
SetCustomerBillingAgreement Errors

Error
Code

Short Message

Long Message

11590

Profile update is not
required

Based on your input request,
profile already up to date.

11592

Subscription profiles are
not supported for recurring
payments

Subscription profiles are not
supported for recurring payments

13122

Transaction refused

Transaction violates PayPal use

13701

Invalid Data

Item Category value is invalid.
Only Digital or Physical are
allowed.

15004

Gateway Decline

This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.

Additional Information

Scenario: When merchant passes
an item category value other than
Digital or Physical.

SetCustomerBillingAgreement Errors
SetCustomerBillingAgreement Errors
Error
Code

Short Message

Long Message

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid argument; BillingType
input field is set to None

10404

Transaction refused
because of an invalid
argument. See additional
error messages for details.

ReturnURL is missing.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid value for request billing
address parameter.

10405

Transaction refused
because of an invalid
argument. See additional
error messages for details.

CancelURL is missing.

CancelURL tag has no content.

10407

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid buyer email address
(BuyerEmail).

Invalid BuyerEmail (badly
formatted or violates SMTP
protocol defined email address
format) or BuyerEmail is passed
as an empty tag.

Name-Value Pair API Developer Guide

August 2012

Additional Information

ReturnURL tag has no content.

251

API Error Codes
SetCustomerBillingAgreement Errors

Error
Code

252

Short Message

Long Message

Additional Information

10436

Transaction refused
because of an invalid
argument. See additional
error messages for details.

PageStyle value exceeds maximum
allowable length.

PageStyle tag is too long.

10437

Transaction refused
because of an invalid
argument. See additional
error messages for details.

cpp-header-image value exceeds
maximum allowable length.

cpp_header_image tag is too
long; maximum length is 127.

10438

Transaction refused
because of an invalid
argument. See additional
error messages for details.

cpp-header-border-color value
exceeds maximum allowable
length.

cpp_header_border_color tag is
too long; maximum length is 6.

10439

Transaction refused
because of an invalid
argument. See additional
error messages for details.

cpp-header-back-color value
exceeds maximum allowable
length.

cpp_header_back_color tag is
too long; maximum length is 6.

10440

Transaction refused
because of an invalid
argument. See additional
error messages for details.

cpp-payflow-color value exceeds
maximum allowable length.

cpp_payflow_color tag is too
long; maximum length is 6.

10471

Transaction refused
because of an invalid
argument. See additional
error messages for details.

ReturnURL is invalid.

ReturnURL tag contains invalid
URL.

10472

Transaction refused
because of an invalid
argument. See additional
error messages for details.

CancelURL is invalid.

CancelURL tag contains invalid
URL.

10476

Transaction refused
because of an invalid
argument. See additional
error messages for details.

10477

Transaction refused
because of an invalid
argument. See additional
error messages for details.

10485

Payment not authorized

Payment has not been authorized
by the user.

11452

Merchant not enabled for
reference transactions

Merchant not enabled for reference
transactions

August 2012

This merchant is not enabled for
Mark reference transaction.
Warning only.

Name-Value Pair API Developer Guide

API Error Codes
GetBillingAgreementCustomerDetails Errors

Error
Code

Short Message

Long Message

Additional Information

11453

Reference transactions
temporarily unavailable.

Reference transaction feature not
currently available; try again later

Feature not enabled because
system is running in standin
mode. Warning only.

11601

Request for billing address
failed

Billing address request is not
enabled for merchant

11602

Request for billing address
failed

Feature not yet available

GetBillingAgreementCustomerDetails Errors
GetBillingAgreementCustomerDetails Errors
Error
Code

Short Message

Long Message

Additional Information

10408

Missing token

Token is missing

Token is missing.

10409

You’re not authorized to
access this info.

Express Checkout token was
issued for a merchant account
other than yours.

Token belongs to a different
merchant.

10410

Invalid token

Token is invalid.

10411

This Express Checkout
session has expired.

This Express Checkout session has
expired. Token value is no longer
valid.

Token expired.

CreateBillingAgreement Errors
CreateBillingAgreement Errors
Error
Code

Short Message

Long Message

Additional Information

10408

Missing token

Token is missing

Token is missing.

10409

You’re not authorized to
access this info.

Express Checkout token was
issued for a merchant account
other than yours.

Token belongs to a different
merchant.

10410

Invalid token

Token is invalid.

10411

This Express Checkout
session has expired.

This Express Checkout session has
expired. Token value is no longer
valid.

Token expired.

Name-Value Pair API Developer Guide

August 2012

253

API Error Codes
UpdateBillingAgreement Errors

Error
Code

Short Message

Long Message

Additional Information

11455

Buyer did not accept billing
agreement

Buyer has not agreed to the
billing agreement.

11456

A successful Billing
Agreement has already
been created for this token.

Transaction refused because of an
invalid argument. See additional
error messages for details.

Token has already been used to
create a billing agreement.

10408

Missing token

Token is missing

Token is missing.

10409

You’re not authorized to
access this info.

Express Checkout token was
issued for a merchant account
other than yours.

Token belongs to a different
merchant.

10410

Invalid token

Token is invalid.

10411

This Express Checkout
session has expired.

This Express Checkout session has
expired. Token value is no longer
valid.

Token expired.

UpdateBillingAgreement Errors
UpdateBillingAgreement Errors

254

Error
Code

Short Message

Long Message

10001

Internal Error

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid argument; description field
or custom field is empty and the
status is active

Check the description and
custom fields of the billing
agreement. Either the description
or custom field is empty and the
status is active or the contents of
one of these fields exceeds the
maximum field length.

10201

Billing Agreement was
cancelled

Billing Agreement was cancelled

Billing agreement has been
cancelled.

10204

User’s account is closed or
restricted

10209

Disabled

Preapproved Payments not
enabled.

Merchant pull is not enabled for
the country or merchant is not
enabled for merchant pull.

10209

Disabled

Preapproved Payments not
enabled.

Account number mismatch
exists for the API caller and the
account the billing agreement
belongs to.

August 2012

Additional Information

Name-Value Pair API Developer Guide

API Error Codes
DoReferenceTransaction Errors

Error
Code

Short Message

Long Message

10211

Invalid billing agreement
ID

Invalid transaction or billing
agreement ID; could not find
Billing Agreement in database

11451

Billing Agreement Id or
transaction Id is not valid

ReferenceID field is empty.

11451

Billing Agreement Id or
transaction Id is not valid

Reference id refers to an invalid
transaction.

11452

Merchant not enabled for
reference transactions

Merchant not enabled for reference
transactions

This merchant is not enabled for
Mark reference transaction.

Additional Information

DoReferenceTransaction Errors
All Reference Transactions-Related API Errors
Error
Code

Short Message

Long Message

10001

Internal Error

10002

Authentication/Authorizati
on Failed

10003

Missing argument

Item name, amount and quantity
are required if item category is
provided.

Scenario: Merchant passes item
category as either Digital or
Physical but does not also pass
one of the following parameters:
name, amount, or quantity.

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

You are not signed up to accept
payment for digitally delivered
goods.

Scenario: Merchant is not signed
up for digital goods but passes
item category as Digital.

10004

Cart item calculation
mismatch.

Cart item calculation mismatch.
The regular non-trial billing period
amount is different than the sum of
the amounts for each item in the
cart.

Scenario: When the regular nontrial billing period amount is
different than the sum of the
amounts for each item in the
cart.

10004

Tax calculation mismatch.

Tax calculation mismatch. The tax
amount for the regular non-trial
billing period is different than the
sum of the tax for each item in the
cart.

Scenario: When the regular nontrial billing period is different
than the sum of the tax for each
item in the cart.

Name-Value Pair API Developer Guide

August 2012

Additional Information

255

API Error Codes
DoReferenceTransaction Errors

Error
Code

Short Message

Long Message

10004

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invalid payment type argument

10009

Transaction refused

The account for the counterparty is
locked or inactive

Merchant is
locked/close/restricted.

10010

Invalid Invoice

Non-ASCII invoice id is not
supported

Non-ASCII characters are used
in InvoiceID field.

10201

Agreement canceled

Billing Agreement was cancelled

Billing agreement is not active.

10202

Exceed max

Transaction would exceed user’s
monthly maximum

Transaction would exceed the
monthly limit.

10203

Action required

Transaction failed, action required
by user

10204

User’s account is closed or
restricted

10205

Risk

Transaction refused due to risk
model

10206

Duplicate

Transaction was already processed

10207

Retry

Transaction failed but user has
alternate funding source

Retry the transaction with an
alternate funding source.

10209

Disabled

Preapproved Payments not
enabled.

Merchants is not enabled for
preapproved payments (PAP);
applies only to legacy PAP
billing agreements.

10210

No Funding

Transaction failed because has no
funding sources

Payee has no funding sources.

Invalid MP ID

Invalid MP ID.
A profile preference is set that
automatically denies this kind of
transaction.

10211
10212

Profile preference setting

A profile preference is set to
automatically deny certain
transactions

10213

Invalid Soft Descriptor

The soft descriptor passed in
contains invalid characters

10214

256

Additional Information

Soft descriptor format error.

10215

Soft Descriptor truncated

The soft descriptor was truncated

10216

Confirmed address required

Transaction refused because a
confirmed address is not available

August 2012

Transaction refused because a
confirmed address is not
available.

Name-Value Pair API Developer Guide

API Error Codes
DoReferenceTransaction Errors

Error
Code

Short Message

Long Message

Additional Information

10400

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Order total is missing.

TotalOrder amount is missing.

10401

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Order total is invalid.

TotalOrder amount is invalid.

10402

Authorization only is not
allowed for merchant.

This merchant account is not
permitted to set PaymentAction? to
Authorization. Please contact
Customer Service.

Merchant is not eligible for auth
settlement.

10406

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The PayerID? value is invalid.

Merchant account number is
invalid.

10412

Duplicate invoice

Payment has already been made
for this InvoiceID?.

Payment already made for the
invoice.

10413

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The totals of the cart item amounts
do not match order amounts.

Total of cart items does not
match order total.

10414

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The amount exceeds the maximum
amount for a single transaction.

Amount exceeds the max
amount for a single txn.

10417

Transaction cannot
complete.

The transaction cannot complete
successfully. Instruct the customer
to use an alternative payment
method.

Account not associated with a
usable funding source.

10417

Transaction cannot
complete.

The transaction cannot complete
successfully. Instruct the customer
to use an alternative payment
method.

Credit card or Billing Agreement
is required to complete payment.

10418

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The currencies of the shopping cart
amounts must be the same.

Currencies in the shopping cart
must be the same.

10420

Transaction refused
because of an invalid
argument. See additional
error messages for details.

PaymentAction? tag is missing.

Name-Value Pair API Developer Guide

August 2012

257

API Error Codes
DoReferenceTransaction Errors

Error
Code

258

Short Message

Long Message

Additional Information

10426

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Item total is invalid.

ItemTotal amount is invalid.

10427

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Shipping total is invalid.

ShippingTotal amount is invalid.

10428

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Handling total is invalid.

HandlingTotal amount is invalid.

10429

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Tax total is invalid.

TaxTotal amount is invalid.

10429

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Item sales tax is invalid

PaymentDetailsItem.Tax field is
invalid. Warning only; API
executes.

10430

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Item amount is missing.

PaymentDetailsItem.Amount
field is missing. Warning only;
API executes.

10431

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Item amount is invalid.

PaymentDetailsItem.Amount
field is invalid. Warning only;
API executes.

10432

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Invoice ID value exceeds
maximum allowable length.

InvoiceID field is too long;
maximum length is 256.

10433

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Value of OrderDescription element
has been truncated.

OrderDescription field is too
long; maximum length is 127.
Warning only; API executes.

10434

Transaction refused
because of an invalid
argument. See additional
error messages for details.

Value of Custom element has been
truncated.

Custom field is too long;
maximum length is 256.
Warning only; API executes.

August 2012

Name-Value Pair API Developer Guide

API Error Codes
DoReferenceTransaction Errors

Error
Code

Short Message

Long Message

Additional Information

10441

Transaction refused
because of an invalid
argument. See additional
error messages for details.

The NotifyURL element value
exceeds maximum allowable
length.

NotifyURL field is too long;
maximum length for notify URL
is 2048.

10442

ButtonSource value
truncated.

The ButtonSource element value
exceeds maximum allowable
length.

ButtonSource field is too long;
maximum length is 32. Warning
only; API executes.

10504

The cvv2 is invalid.

This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.

CVV2 field is invalid.

10527

Invalid Data

This transaction cannot be
processed. Please enter a valid
credit card number and type.

CreditCardNumber and/or
CreditCardType is invalid.

10537

Risk Control Country Filter
Failure

The transaction was refused
because the country was prohibited
as a result of your Country Monitor
Risk Control Settings.

Transaction refused due to
country monitor risk control.

10538

Risk Control Max Amount
Failure

The transaction was refused
because the maximum amount was
excused as a result of your
Maximum Amount Risk Control
Settings.

Transaction refused due to max
amount risk control.

10539

Payment declined by your
Risk Controls settings:
PayPal Risk Model.

Payment declined by your Risk
Controls settings: PayPal Risk
Model.

Transaction declined by Risk
Control settings: PayPal Risk
model.

10546

Gateway Decline

This transaction cannot be
processed.

IP fraud models failed.

10560

Invalid Data

The issue number of the credit card
is invalid.

IssueNumber is invalid.

10567

Invalid Data

A Start Date or Issue Number is
required.

None of Start date or issue
number is specified (only applies
to Switch credit cards).

10600

Authorization voided

Authorization voided.

10601

Authorization expired.

Authorization has expired

10621

Order has expired.

10622

Order is voided.

10623

Maximum number of
authorization allowed for
the order is reached.

Maximum number of authorization
allowed for the order is reached.

Name-Value Pair API Developer Guide

August 2012

259

API Error Codes
DoReferenceTransaction Errors

Error
Code

260

Short Message

Long Message

Additional Information

10725

Shipping Address Country
Error

There was an error in the Shipping
Address Country field

Shipping address error in
country field.

10727

Shipping Address1 Empty

The field Shipping Address1 is
required

Shipping address error in
address1 field.

10728

Shipping Address City
Empty

The field Shipping Address City is
required

Shipping address error in city
field.

10729

Shipping Address State
Empty

The field Shipping Address State is
required

Shipping address error in state
field.

10730

Shipping Address Postal
Code Empty

The field Shipping Address Postal
Code is required

Shipping address error in postal
code.

10731

Shipping Address Country
Empty

The field Shipping Address
Country is required

Country code is empty in
shipping address.

10736

Shipping Address Invalid
City State Postal Code

A match of the Shipping Address
City, State, and Postal Code failed.

Match of shipping address, city,
state, and postal code failed.

10747

Invalid Data

This transaction cannot be
processed without a valid IP
address.

IPAddress field is invalid.

10748

Invalid Data

This transaction cannot be
processed without a Credit Card
Verification number.

CVV2 field is missing.

10755

Unsupported Currency.

This transaction cannot be
processed due to an unsupported
currency.

11084

User does not have a good
funding source with which
to pay.

User does not have a good funding
source with which to pay.

Scenario: The credit card
associated with the account
could not be used and there is no
other funding source with which
to complete the transaction.

11091

The transaction was
blocked as it would exceed
the sending limit for this
buyer.

The transaction was blocked as it
would exceed the sending limit for
this buyer.

The transaction was declined by
PayPal. Please have the buyer
contact PayPal Customer
Service.

11302

Cannot pay self

The transaction was refused
because you cannot send money to
yourself.

Cannot pay self. Merchant is
referencing own transaction.

11451

Billing Agreement Id or
transaction Id is not valid

Invalid reference id.

August 2012

Name-Value Pair API Developer Guide

API Error Codes
DoReferenceTransaction Errors

Error
Code

Short Message

Long Message

Additional Information

11451

Billing Agreement Id or
transaction Id is not valid

Reference transaction is not
associated with a billing
agreement.

11451

Billing Agreement Id or
transaction Id is not valid

Reference id either not found or
could not be decrypted.

11451

Billing Agreement Id or
transaction Id is not valid

Reference id either not found or
could not be decrypted.

11452

Merchant not enabled for
reference transactions

Merchant not enabled for reference
transactions

This merchant is not enabled for
Mark reference transaction.

11453

Reference transactions
temporarily unavailable.

Reference transaction feature not
currently available; try again later

Feature wired off.

11453

Reference transactions
temporarily unavailable.

Reference transaction feature not
currently available; try again later

Feature not supported in standin.

11454

Warning: Could not send
email to the buyer

Warning: Could not send email to
the buyer

Failed to send email to buyer.
This error is not fatal and
generates a warning.

11459

Invalid Data

The shipping address must match
the user’s address in the PayPal
account.

The shipping address on file
does not match the requested
shipping address.

11610

Payment Pending your
review in Fraud
Management Filters

Payment Pending your review in
Fraud Management Filters

11611

Transaction blocked by
your settings in FMF

Transaction blocked by your
settings in FMF

11612

Could not process your
request to accept/deny the
transaction

Could not process your request to
accept/deny the transaction

13122

Transaction refused

Transaction violates PayPal Use

13701

Invalid Data

Item Category value is invalid.
Only Digital or Physical are
allowed.

Scenario: When merchant passes
an item category value other than
Digital or Physical.

18014

Gateway Decline

This transaction cannot be
processed.

This transaction cannot be
processed without a Credit Card
Verification number.

Name-Value Pair API Developer Guide

August 2012

261

API Error Codes
AddressVerify API Errors

AddressVerify API Errors
AddressVerify API Errors
Error Code

Short Message

Long Message

10004

Transaction refused because
of an invalid argument. See
additional error messages
for details.

Invalid email format.

10004

Transaction refused because
of an invalid argument. See
additional error messages
for details.

Invalid street format

10004

Transaction refused because
of an invalid argument. See
additional error messages
for details.

Invalid zip format

10009

The API is disabled.

The Address API is currently disabled

ManagePendingTransactionStatus API Errors
ManagePendingTransactionStatus API Errors

262

Error Code

Short Message

Long Message

11614

Could not process your request
to accept/deny the transaction

Could not process your request to accept/deny the transaction

11614

The transaction has already
been Accepted/Denied and the
status cannot be changed

The transaction has already been Accepted/Denied and the
status cannot be changed

August 2012

Name-Value Pair API Developer Guide

Countries and Regions
Supported by PayPal
PayPal uses 2-character IS0-3166-1 codes for specifying countries and regions that are
supported in fields and variables. Countries marked with an asterisk ( * ) are not supported for
PayPal Payments Pro and Virtual Terminal.

Country or Region

Country or Region Code

ÅLAND ISLANDS

ALBANIA

ALGERIA *

DZ *

AMERICAN SAMOA

ANDORRA

ANGUILLA

ANTARCTICA *

AQ *

ANTIGUA AND BARBUDA

ARGENTINA

ARMENIA

ARUBA

AUSTRALIA

AUSTRIA

AZERBAIJAN

BAHAMAS

BAHRAIN

BANGLADESH

BARBADOS

BELGIUM

BELIZE

BENIN

BERMUDA

BHUTAN

BOSNIA-HERZEGOVINA

Name-Value Pair API Developer Guide

August 2012

263

264

Countries and Regions Supported by PayPal

Country or Region

Country or Region Code

BOTSWANA

BOUVET ISLAND *

BV *

BRAZIL

BRITISH INDIAN OCEAN TERRITORY *

IO *

BRUNEI DARUSSALAM

BULGARIA

BURKINA FASO

CANADA

CAPE VERDE

CAYMAN ISLANDS

CENTRAL AFRICAN REPUBLIC *

CF *

CHILE

CHINA

CHRISTMAS ISLAND *

CX *

COCOS (KEELING) ISLANDS

COLOMBIA

COOK ISLANDS

COSTA RICA

CYPRUS

CZECH REPUBLIC

DENMARK

DJIBOUTI

DOMINICA

DOMINICAN REPUBLIC

ECUADOR

EGYPT

EL SALVADOR

ESTONIA

FALKLAND ISLANDS (MALVINAS)

FAROE ISLANDS

FIJI

August 2012

Name-Value Pair API Developer Guide

Countries and Regions Supported by PayPal

Country or Region

Country or Region Code

FINLAND

FRANCE

FRENCH GUIANA

FRENCH POLYNESIA

FRENCH SOUTHERN TERRITORIES

GABON

GAMBIA

GEORGIA

GERMANY

GHANA

GIBRALTAR

GREECE

GREENLAND

GRENADA

GUADELOUPE

GUAM

GUERNSEY

GUYANA

HEARD ISLAND AND MCDONALD ISLANDS *

HM *

HOLY SEE (VATICAN CITY STATE)

HONDURAS

HONG KONG

HUNGARY

ICELAND

INDIA

INDONESIA

IRELAND

ISLE OF MAN

ISRAEL

ITALY

JAMAICA

Name-Value Pair API Developer Guide

August 2012

265

266

Countries and Regions Supported by PayPal

Country or Region

Country or Region Code

JAPAN

JERSEY

JORDAN

KAZAKHSTAN

KIRIBATI

KOREA, REPUBLIC OF

KUWAIT

KYRGYZSTAN

LATVIA

LESOTHO

LIECHTENSTEIN

LITHUANIA

LUXEMBOURG

MACAO

MACEDONIA

MADAGASCAR

MALAWI

MALAYSIA

MALTA

MARSHALL ISLANDS

MARTINIQUE

MAURITANIA

MAURITIUS

MAYOTTE

MEXICO

MICRONESIA, FEDERATED STATES OF

MOLDOVA, REPUBLIC OF

MONACO

MONGOLIA

MONTENEGRO

MONTSERRAT

August 2012

Name-Value Pair API Developer Guide

Countries and Regions Supported by PayPal

Country or Region

Country or Region Code

MOROCCO

MOZAMBIQUE

NAMIBIA

NAURU

NEPAL *

NP *

NETHERLANDS

NETHERLANDS ANTILLES

NEW CALEDONIA

NEW ZEALAND

NICARAGUA

NIGER

NIUE

NORFOLK ISLAND

NORTHERN MARIANA ISLANDS

NORWAY

OMAN

PALAU

PALESTINE

PANAMA

PARAGUAY

PERU

PHILIPPINES

PITCAIRN

POLAND

PORTUGAL

PUERTO RICO

QATAR

REUNION

ROMANIA

RUSSIAN FEDERATION

RWANDA

Name-Value Pair API Developer Guide

August 2012

267

268

Countries and Regions Supported by PayPal

Country or Region

Country or Region Code

SAINT HELENA

SAINT KITTS AND NEVIS

SAINT LUCIA

SAINT PIERRE AND MIQUELON

SAINT VINCENT AND THE GRENADINES

SAMOA

SAN MARINO

SAO TOME AND PRINCIPE *

ST *

SAUDI ARABIA

SENEGAL

SERBIA

SEYCHELLES

SINGAPORE

SLOVAKIA

SLOVENIA

SOLOMON ISLANDS

SOUTH AFRICA

SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS

SPAIN

SURINAME

SVALBARD AND JAN MAYEN

SWAZILAND

SWEDEN

SWITZERLAND

TAIWAN, PROVINCE OF CHINA

TANZANIA, UNITED REPUBLIC OF

THAILAND

TIMOR-LESTE

TOGO

TOKELAU

TONGA

August 2012

Name-Value Pair API Developer Guide

Countries and Regions Supported by PayPal

Country or Region

Country or Region Code

TRINIDAD AND TOBAGO

TUNISIA

TURKEY

TURKMENISTAN

TURKS AND CAICOS ISLANDS

TUVALU

UGANDA

UKRAINE

UNITED ARAB EMIRATES

UNITED KINGDOM

UNITED STATES

UNITED STATES MINOR OUTLYING ISLANDS

URUGUAY

UZBEKISTAN

VANUATU

VENEZUELA

VIET NAM

VIRGIN ISLANDS, BRITISH

VIRGIN ISLANDS, U.S.

WALLIS AND FUTUNA

WESTERN SAHARA

ZAMBIA

Name-Value Pair API Developer Guide

August 2012

269

270

Countries and Regions Supported by PayPal

August 2012

Name-Value Pair API Developer Guide

State and Province Codes

Canadian Province or U.S. State

Abbreviation

Alberta

British Columbia

Manitoba

New Brunswick

Newfoundland and Labrador

Northwest Territories

Nova Scotia

Nunavut

Ontario

Prince Edward Island

Quebec

Saskatchewan

Yukon

Alabama

Alaska

American Samoa

Arizona

Arkansas

California

Colorado

Connecticut

Delaware

District of Columbia

Federated States of Micronesia

Florida

Georgia

Name-Value Pair API Developer Guide

August 2012

271

272

State and Province Codes

Canadian Province or U.S. State

Abbreviation

Guam

Hawaii

Idaho

Illinois

Indiana

Iowa

Kansas

Kentucky

Louisiana

Maine

Marshall Islands

Maryland

Massachusetts

Michigan

Minnesota

Mississippi

Missouri

Montana

Nebraska

Nevada

New Hampshire

New Jersey

New Mexico

New York

North Carolina

North Dakota

Northern Mariana Islands

Ohio

Oklahoma

Oregon

Palau

August 2012

Name-Value Pair API Developer Guide

State and Province Codes

Canadian Province or U.S. State

Abbreviation

Pennsylvania

Puerto Rico

Rhode Island

South Carolina

South Dakota

Tennessee

Texas

Utah

Vermont

Virgin Islands

Virginia

Washington

West Virginia

Wisconsin

Wyoming

Armed Forces Americas

Armed Forces

Armed Forces Pacific

Name-Value Pair API Developer Guide

August 2012

273

274

State and Province Codes

August 2012

Name-Value Pair API Developer Guide

Currency Codes

PayPal uses 3-character ISO-4217 codes for specifying currencies in fields and variables.
Currencies and Currency Codes Supported by PayPal
Currency

Currency Code

Australian Dollar

AUD

Brazilian Real

BRL

N O TE :

This currency is supported as a payment
currency and a currency balance for in-country
PayPal accounts only.

Canadian Dollar

CAD

Czech Koruna

CZK

Danish Krone

DKK

Euro

EUR

Hong Kong Dollar

HKD

Hungarian Forint

HUF

Israeli New Sheqel

ILS

Japanese Yen

JPY

Malaysian Ringgit

MYR

N O TE :

This currency is supported as a payment
currency and a currency balance for in-country
PayPal accounts only.

Mexican Peso

MXN

Norwegian Krone

NOK

New Zealand Dollar

NZD

Philippine Peso

PHP

Polish Zloty

PLN

Pound Sterling

GBP

Singapore Dollar

SGD

Swedish Krona

SEK

Swiss Franc

CHF

Taiwan New Dollar

TWD

Name-Value Pair API Developer Guide

August 2012

275

Currency Codes

Currency

Currency Code

Thai Baht

THB

Turkish Lira

TRY

N O TE :

This currency is supported as a payment
currency and a currency balance for in-country
PayPal accounts only.

U.S. Dollar

USD

Currencies and Currency Codes Supported by Express Checkout and Direct Payment

276

Express
Checkout
Currency

Currency
Code

Direct Payment
Currency for Specified
Card in United States

Direct Payment
Currency for Specified
Card in United Kingdom

Direct Payment
Currency for Specified
Card in Canada

Australian
Dollar

AUD

Visa, MasterCard

Canadian
Dollar

CAD

Visa, MasterCard

Czech Koruna

CZK

Visa, MasterCard

Danish Krone

DKK

Visa, MasterCard

Euro

EUR

Visa, MasterCard

Hong Kong
Dollar

HKD

Visa, MasterCard

Hungarian
Forint

HUF

Visa, MasterCard

Japanese Yen

JPY

Visa, MasterCard

Norwegian
Krone

NOK

Visa, MasterCard

New Zealand
Dollar

NZD

Visa, MasterCard

Polish Zloty

PLN

Visa, MasterCard

Pound Sterling

GBP

Visa, MasterCard, Maestro

Visa, MasterCard

Singapore
Dollar

SGD

Visa, MasterCard

Swedish Krona

SEK

Visa, MasterCard

Swiss Franc

CHF

Visa, MasterCard

U.S. Dollar

USD

Visa, MasterCard

Visa, MasterCard,
Discover, American
Express

August 2012

Name-Value Pair API Developer Guide

AVS and CVV2 Response Codes

AVS Response Codes
Related information:
DoDirectPayment Response Fields

AVS Response Codes for Visa, MasterCard, Discover, and American
Express
AVS Code

Meaning

Matched Details

Address

Address only (no ZIP code)

International “A”

Address only (no ZIP code)

International “N”

None
NOT E :

The transaction is declined.

International “X”

Address and Postal Code

Not allowed for MOTO
(Internet/Phone) transactions

Not applicable
NOT E :

The transaction is declined.

UK-specific “X”

Address and Postal Code

Global Unavailable

Not applicable

International Unavailable

Not applicable

Address

Address and Postal Code

None
NOT E :

The transaction is declined.

Postal (International “Z”)

Postal Code only (no Address)

Retry

Not applicable

Service not Supported

Not applicable

Unavailable

Not applicable

Whole ZIP

Nine-digit ZIP code (no Address)

Name-Value Pair API Developer Guide

August 2012

277

AVS and CVV2 Response Codes
AVS Response Codes

AVS Code

Meaning

Matched Details

Exact match

Address and nine-digit ZIP code

Yes

Address and five-digit ZIP

ZIP

Five-digit ZIP code (no Address)

All others

Error

Not applicable

Related information:
DoDirectPayment Response Fields

AVS Response Codes for Maestro
AVS Code

Meaning

Matched Details

All the address information matched.

All information matched

None of the address information
matched.

None
N O TE :

The transaction is declined.

Part of the address information
matched.

Partial

The merchant did not provide AVS
information. Not processed.

Not applicable

Address not checked, or acquirer had
no response. Service not available.

Not applicable

Null

No AVS response was obtained.
Default value of field.

Not applicable

Related information:
DoDirectPayment Response Fields

278

August 2012

Name-Value Pair API Developer Guide

AVS and CVV2 Response Codes
CVV2 Response Codes

CVV2 Response Codes

CVV2 Response Codes for Visa, MasterCard, Discover, and American
Express
CVV2 Code

Meaning

Matched Details

Error - Unrecognized or Unknown
response

Not applicable

Invalid or Null

Not applicable

Match

CVV2CSC

No match

None

Not processed

Not applicable

Service not supported

Not applicable

Service not available

Not applicable

No response

Not applicable

CVV2 Response Codes for Maestro
CVV2 Code

Meaning

Matched Details

Matched

CVV2

No match

None

The merchant has not implemented
CVV2 code handling

Not applicable

Merchant has indicated that CVV2 is
not present on card

Not applicable

Service not available

Not applicable

All others

Error

Not applicable

Name-Value Pair API Developer Guide

August 2012

279

280

AVS and CVV2 Response Codes
CVV2 Response Codes

August 2012

Name-Value Pair API Developer Guide

About Previous Versions of the
API
Previous versions of the API can still be used; however, PayPal recommends using the latest
version whenever possible. Unless specifically specified, API operations default to the latest
version.

What’s New in Version 92.0
Updated for 92.0. Added new MsgSubID field for the following APIs for both requests and
responsees: RefundTransaction; DoReferenceTransaction; DoAuthorization; and DoCapture.

What’s New in Version 89.0
Updated for 89.0. Added new field to SetExpressCheckout and DoReferenceTransaction
Request APIs. Added new error to DoReferenceTransaction Request API.

What’s New in Version 88.0
Maintenance release, updated for 88.0.

What’s New in Version 85.0
No new features added; solely a maintenance release.

What’s New in Version 84.0

Name-Value Pair API Developer Guide

August 2012

281

What’s New in Version 84.0

New Field in RefundTransaction Response

Field

Description

REFUNDINFO

Contains refund payment status information.
This field is available since version 84.0.

New RefundInfoType in RefundTransaction Response
Field

Description

REFUNDSTATUS

Status of the refund. It is one of the following values:
 instant
 delayed
This field is available since version 84.0.

PENDINGREASON

Reason that the payment is delayed. It is one of the following values:
 none – The refund is instant.
 echeck – The refund is delayed.
This field is available since version 84.0.

New Field in DoReferenceTransactionResponseDetailsType
Field

Description

PAYMENTADVICECODE

Response code from the processor when a recurring transaction is declined.
For details on the meanings of the codes, see
https://merchant.paypal.com/us/cgi-bin/?&cmd=_rendercontent&content_ID=merchant/cc_compliance_error_codes
This field is available since version 84.0.

New Field in DoDirectPaymentResponse

282

Field

Description

PAYMENTADVICECODE

August 2012

Name-Value Pair API Developer Guide

What’s New in Version 82.0

New Field in DoCapture Request

Field

Description

MERCHANTSTOREDETAILS

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

New MerchantStoreDetailsType in DoCapture Request
Field

Description

STOREID

ID of the merchant store. This field is required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters
This field is available since version 84.0.

TERMINALID

(Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.

New Fields in RefundTransaction Request

Field

Description

MERCHANTSTOREDETAILS

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

RETRYUNTIL

(Optional) Maximum time until you must retry the refund.
NOT E :

This field does not apply to point-of-sale transactions.

This field is available since version 82.0.

Name-Value Pair API Developer Guide

August 2012

283

What’s New in Version 82.0

Field

Description

REFUNDSOURCE

This field does not apply to point-of-sale transactions.

This field is available since version 82.0.
REFUNDTYPE

New MerchantStoreDetailsType in RefundTransaction Request

284

Field

Description

STOREID

ID of the merchant store. This field is required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters
This field is available since version 84.0.

TERMINALID

(Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.

August 2012

Name-Value Pair API Developer Guide

What’s New in Version 80.0

What’s New in Version 80.0
New Fields in PaymentDetailsType in DoReferenceTransaction Request

Field

Description

RECURRING

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

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.

What’s New in Version 74.0
New Behavior of DoExpressCheckoutPayment
By default, the DoExpressCheckoutPayment API operation is idempotent for all API
callers. You can call DoExpressCheckoutPayment up to a maximum of 10 times, and it
returns the same result. The exceptions are when DoExpressCheckoutPayment generates
an error or the token expires.
This functionality only works with version 74.0 or greater. There is no change to
DoExpressCheckoutPayment functionality if you are not updating to the latest version of
the API.
If you update to version 74.0 or higher but want to opt out of this functionality, contact PayPal.

New DoExpressCheckoutPayment Error Code
Error
Code
13751

Short Message

Long Message

Could not retrieve the
original successful
response.

Transaction completed
successfully, but could not
retrieve the original successful
response.

Name-Value Pair API Developer Guide

August 2012

Correcting This Error...

285

What’s New in Version 72.0

What’s New in Version 72.0
New TaxIdDetailsType Structure in SetExpressCheckout Request
TaxIdDetailsType Fields
Field

Description

TAXIDTYPE

New field
The buyer’s tax ID type. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for
businesses.

TAXID

New field
The buyer’s tax ID. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID is 11 single-byte character for individuals and 14
single-byte characters for businesses.

New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response
TaxIdDetailsType Fields

286

Field

Description

TAXIDTYPE

New field
The buyer’s tax ID type. This field is required for Brazil and used for Brazil only.
For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for
businesses.

TAXID

August 2012

Name-Value Pair API Developer Guide

What’s New in Version 69

What’s New in Version 69
New PaymentDetailsItemType Structure in
CreateRecurringPaymentsProfile Request
PaymentDetailsItemType Fields
Field

Description

L_PAYMENTREQUEST_n_IT
EMCATEGORYm

New field
Indicates whether the item is digital or physical goods. For digital goods, this field
is required and you must set it to Digital to get the best rates. It is one of the
following values:
 Digital
 Physical
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_ITEMCATEGORY0,
L_PAYMENTREQUEST_n_ITEMCATEGORY1).

L_PAYMENTREQUEST_n_NA
MEm

New field
Item name.This field is required when you pass a value for ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).
Character length and limitations: 127 single-byte characters

L_PAYMENTREQUEST_n_DE
SCm

New field
(Optional) Item description.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_DESC0, L_PAYMENTREQUEST_n_DESC1).
Character length and limitations: 127 single-byte characters

L_PAYMENTREQUEST_n_AM
Tm

New field
Cost of item. This field is required when you pass a value for ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).
Character length and limitations: Must not exceed $10,000 USD in any currency.
No currency symbol. Regardless of currency, decimal separator must be a period
(.), and the optional thousands separator must be a comma (,). Equivalent to nine
characters maximum for USD.

L_PAYMENTREQUEST_n_NU
MBERm

New field
(Optional) Item number.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NUMBER0, L_PAYMENTREQUEST_n_NUMBER1).

Name-Value Pair API Developer Guide

August 2012

287

What’s New in Version 69

Field

Description

L_PAYMENTREQUEST_n_QT
Ym

New field
Item quantity. This field is required when you pass a value for ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).
Character length and limitations: Any positive integer

L_PAYMENTREQUEST_n_TA
XAMTm

New field
(Optional) Item sales tax.
These parameters must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_TAXAMT0, L_PAYMENTREQUEST_n_TAXAMT1).
Character length and limitations: Must not exceed $10,000 USD in any currency.
No currency symbol. Regardless of currency, decimal separator must be a period
(.), and the optional thousands separator must be a comma (,). Equivalent to nine
characters maximum for USD.

Changes to PaymentDetailsItemType in DoReferenceTransaction Request
PaymentDetailsItemType Fields
Field

Description

L_ITEMCATEGORYn

New field
Indicates whether the item is digital or physical goods. For digital goods, this
field is required and you must set it to Digital to get the best rates. It is one
of the following values:
 Digital
 Physical
These parameters must be ordered sequentially beginning with 0 (for example
L_ITEMCATEGORY0, L_ITEMCATEGORY1).

L_NAMEn

Item name. This field is required when you pass a value for ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_NAME0, L_NAME1).
Character length and limitations: 127 single-byte characters

L_AMTn

Cost of item. This field is required when you pass a value for ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_AMT0, L_AMT1).
N O TE :

If you specify a value for L_AMTn, you must specify a value for
ITEMAMT.

288

August 2012

Name-Value Pair API Developer Guide

What’s New in Version 66

Field

Description

L_QTYn

Item quantity. This field is required when you pass a value for
ItemCategory.
These parameters must be ordered sequentially beginning with 0 (for example
L_QTY0, L_QTY1).
Character length and limitations: Any positive integer

What’s New in Version 66
Changes to PaymentDetailsType in SetExpressCheckout and
DoExpressCheckoutPayment Requests
PaymentDetailsType Fields
Field

Description

PAYMENTREQUEST_n_ITEMAMT
ITEMAMT (deprecated)

Sum of cost of all items in this order. For digital goods, this field is required.
N O TE :

PAYMENTREQUEST_n_ITEMAMT is required if you specify
L_PAYMENTREQUEST_n_AMTm.

ITEMAMT is deprecated since version 63.0. Use
PAYMENTREQUEST_0_ITEMAMT instead.
PAYMENTREQUEST_n_PAYMENT
ACTION
PAYMENTACTION (deprecated)

How you want to obtain payment. When implementing digital goods, this field
is required and you must set it to Sale.
PAYMENTACTION is deprecated since version 63.0. Use
PAYMENTREQUEST_0_PAYMENTACTION instead.

Changes to PaymentDetailsItemTypein SetExpressCheckout and
DoExpressCheckoutPayment Requests
PaymentDetailsItemType Fields
Field

Description

L_PAYMENTREQUEST_n_ITEMC
ATEGORYm

New field
Indicates whether the item is digital or physical goods. This field is available
since version 65.1. For digital goods this field is required and you must set it to
Digital. It is one of the following values:
 Digital
 Physical

Name-Value Pair API Developer Guide

August 2012

289

What’s New in Version 66

Field

Description

L_PAYMENTREQUEST_n_NAME

Item name. For digital goods, this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).
Character length and limitations: 127 single-byte characters
L_NAMEn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_NAMEm instead.

L_NAMEn (deprecated)

L_PAYMENTREQUEST_n_DESC
m

L_DESCn (deprecated)

L_PAYMENTREQUEST_n_AMTm
L_AMTn (deprecated)

Item description. For digital goods, this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_DESC0, L_PAYMENTREQUEST_n_DESC1).
Character length and limitations: 127 single-byte characters
L_DESCn is deprecated since version 63.0. Use
L_PAYMENTREQUEST_0_DESCm instead.
Cost of item. For digital goods, this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).
N O TE :

If you specify a value for L_PAYMENTREQUEST_n_AMTm, you must
specify a value for PAYMENTREQUEST_n_ITEMAMT.

Character length and limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Regardless of currency, decimal separator must
be a period (.), and the optional thousands separator must be a comma (,).
Equivalent to nine characters maximum for USD.
L_AMTn is deprecated since version 63.0. Use L_PAYMENTREQUEST_0_AMTm
instead.
L_PAYMENTREQUEST_n_QTYm
L_QTYn (deprecated)

290

Item quantity. For digital goods, this field is required.
You can specify up to 10 payments, where n is a digit between 0 and 9,
inclusive, and m specifies the list item within the payment. These parameters
must be ordered sequentially beginning with 0 (for example
L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).
Character length and limitations: Any positive integer
L_QTYn is deprecated since version 63.0. Use L_PAYMENTREQUEST_0_QTYm
instead.

August 2012

Name-Value Pair API Developer Guide

What’s New in Version 66

Changes to PaymentDetailsItemType in GetExpressCheckoutDetails
Response
Field

Description

L_PAYMENTREQUEST_n_ITEMC
ATEGORYm

New field
Inicates whethe item is digital or physical goods. For digital goods this field is
required and you must set it to Digital. It is one of the following values:
 Digital
 Physical
This field is available since version 65.1.

Name-Value Pair API Developer Guide

August 2012

291

What’s New in Version 66

292

August 2012

Name-Value Pair API Developer Guide

Revision History

Date

Description

10 August 2012

Maintenance release. Added CVV2 response codes E and I for Visa,
Mastercard, Discover and American Express.

7 August 2012

Maintenance release. New 10486 error code added for redirects when the
process declines the transaction: The transaction couldn’t be completed. Please
redirect your customer to PayPal.

10 July 2012

Updated for 92.0. Added new MsgSubID field for the following APIs for both
requests and responsees: RefundTransaction; DoReferenceTransaction;
DoAuthorization; and DoCapture.

12 June 2012

Maintenance release

22 May 2012

Maintenance release

2 May 2012

Updated for 89.0. Added new field to SetExpressCheckout and
DoReferenceTransaction Request APIs. Added new error to
DoReferenceTransaction Request API.

3 April 2012

Updated references to Website Payments Standard and Website Payments Pro to
PayPal Payments Standard and PayPal Payments Pro, respectively.

14 February 2012

Maintenance release

24 January 2012

Maintenance release, updated for 85.0.

1November 2011

Updated for 84.0. Added new field and a new type to RefundTransaction API
request. Added new field to DoDirectPayment API and
DoReferenceTransaction API responses. Edits to improve accuracy.

1 September 2011

General edits to improve consistency.

5 April 2011

Updated for 71.0. Added new fields to the DoExpressCheckout API response to
return information about funds that are being held and the seller’s encrypted
account number.

8 March 2011

Updated for 69.0. Added more digital goods support to the
CreateRecurringPaymentsProfile and DoReferenceTransaction APIs to enable
the merchant to obtain the best rates for digital goods.

26 January 2011

Updated for 66.0. Describes changes to the ExpressCheckout API for
implementing Digital Goods.

15 September 2010

Updated for 64.4, including addition of ProtectionEligibilityType field.

Name-Value Pair API Developer Guide

August 2012

293

Date

Description

11 May 2010

Updated for 63.0. Added new NVP API fields to use in version 63.0 Express
Checkout integrations. Deprecated old fields. Updated billing agreement API
with functionality to obtain the latest billing address and to skip billing
agreement creation. Added ReverseTransaction API.

10 March 2010

Updated information for 62.0: Describes Express Checkout fields recommended
to be used in applications that enable implementing parallel payments for a
marketplace.

21 January 2010

Updated information for 61.0: Added Express Checkout fields enabling you to
provide gift and insurance options to the PayPal checkout pages.

7 October 2009

Updated information for 60.0: updated currency table with new currencies, and
added Express Checkout API fields for Immediatee Payment and eBay.

16 June 2009

Updated information for 58.0: added GetPalDetails API and fields for payment
review.

22 May 2009

Minor update to version 57.0; added CreateBillingAgreement to
Enterprise edition.

08 April 2009

Updated information for 57.0: Express Checkout Callback API and error codes.

26 Nov. 2008

Updated information for 55.0.

23 Sept. 2008

Added information about using billing agreements with SetExpressCheckout.

3 Sept. 2008

Added information about payment review to GetTransactionDetails.

June 2008

Rearranged material, added error codes, and moved some material to the
Express Checkout Integration Guide.

April 2008

Added Fraud Management Filters information. Changed recurring payments
information.

February 2008

Added that ther VERSION parameter must be 50.0 in the API call to use
recurring payments.

January 2008






September 2007





August 2007

294

Added billing agreement fields to SetExpressCheckout for recurring
payments
Updated CreateRecurringPaymentsProfile for new recurring payments
features.
Added new recurring payments APIs
Added DoNonReferencedCredit API
Update eBay auctions for Express Checkout section
Added fields for the giropay payment method to Express Checkout APIs
Added Direct Payment error 10571.

Added recurring payments concepts, modified SetExpressCheckout,
DoExpressCheckoutPayment, DoReferenceTransaction, and added
additional DoReferenceTransaction error codes.

August 2012

Name-Value Pair API Developer Guide

Date

Description

April 2007

Added Recurring Payments APIs: SetCustomerBillingAgreement,
GetBillingAgreementCustomerDetails, and
CreateRecurringPaymentsProfile.

February 2007

Bug fixes including updating Line Item Details for Direct Payment and Express
Checkout APIs, changing some parameters to optional in DoDirectPayment,
adding SHIPTOCOUNTRYCODE, and adding Switch/Solo codes for AVS and
CVV2.

December 2006

Updates for bug fixes.

October 2006

First public release.

11 May 2010

Added new NVP API fields to use in version 63.0 Express Checkout
integrations. Deprecated old fields. Updated billing agreement API with
functionality to obtain the latest billing address and to skip billing agreement
creation. Added ReverseTransaction API.

Name-Value Pair API Developer Guide

August 2012

295

296

August 2012

Name-Value Pair API Developer Guide

Index

Numerics
3-D Secure request fields 47
3D Secure response fields 50

A
ACCT request field 42, 52, 142, 160, 177, 190
ACCT response field 152
ACTION request field 133, 154
Activation Details request fields 141
ADDITIONALBILLINGCYCLES request field 156
Address request fields 43, 53, 143, 160, 178
Address response fields 124, 153
Address Verify request fields 25
Address Verify response fields 26
ADDRESSOWNER response field 124, 153
ADDRESSSTATUS response field 82, 124, 148, 153,
167
AddressVerify API operation 25
AddressVerify request message 25
AddressVerify response message 26
ADDROVERRIDE request field 61
AGGREGATEAMOUNT response field 147
AGGREGATEOPTIONALAMOUNT response
field 147
ALLOWEDPAYMENTMETHOD request field 70, 98
ALLOWEDPAYMENTMETHOD respo nse field 86
ALLOWNOTE request field 61
ALLOWPUSHFUNDING request field 76
American Express AVS response codes 277
American Express CVV2 response codes 279
AMT request field 27, 32, 36, 43, 51, 59, 67, 94, 139,
155, 156, 158, 173, 185
AMT response field 33, 48, 83, 109, 126, 131, 150, 180
AUCTI ONITEMNUMBER reque st field 190
Auction Information response fields 131
AUD 275, 276
Australian Dollar 275, 276
Authorization and Capture API Operation Reference 27
Authorization Type response fields 34, 37
AUTHORIZATIONID request field 27, 36, 39

Name-Value Pair API Developer Guide

AUTHORIZATIONID response field 29, 37, 39
AUTHSTATUS3DS request field 47
AUTOBILLAMT request field 138
AUTOBILLOUTAMT request field 157
AUTOBILLOUTAMT response field 147
AVS and CVV2 response codes 277
AVS response codes 277
AVSCODE response field 48, 178

B
BA Update request fields 168
BA Update response fields 168
BANKTXNPENDINGURL request field 64
BAUpdate API operation 168
BAUpdate request message 168
BAUpdate response message 168
Bill Outstanding Amount request fields 155
Bill Outstanding Amount response fields 155
Billing Period Details request fields 139, 158
Billing Period Details response fields 148
BILLINGAGREEMENTID response field 106, 162,
178
BILLINGAGREEMENTSTATUS request field 168
BILLINGAGREEMENTSTATUS response fie ld 169
BILLINGFREQUENCY request field 139
BILLINGFREQUENCY response field 149
BILLINGPERIOD request field 139
BILLINGPERIOD response field 148
BILLINGTYPE request field 77, 165
BillOutstanding API operation 155
BillOutstandingAmount request message 155
BillOutstandingAmount response message 155
BRANDNAME request field 64
Brazilian Real 275
BRL 275
BUSINESS request field 143
BUSINESS response field 81
BUTTONSOURCE request field 45, 94, 174
Buyer Details request fields 75
BUYEREMAILOPTINENABLE request field 65

August 2012

297

Index

BUYERID request field 75
BUYERID response field 131
BUYERMARKETINGEMAIL request field 93
BUYERMARKETINGEMAIL response field 80, 122
BUYERREGISTRATIONDATE request field 76
BUYERUSERNAME request field 76

C
CAD 275, 276
Callback API operation 55
CALLBACK request field 60
Callback request fields 55
Callback request message 55
Callback response fields 58
Callback response message 58
CALLBACKTIMEOUT request field 60
CALLBACKVERSION request field 61
Canadian Dollar 275, 276
CANCELURL request field 60, 162
CAVV request field 48
CHANNELTYPE request field 64
character encoding 16
CHECKOUTSTATUS response field 80
CHF 275, 276
CITY request field 43, 53, 144, 160, 178
CLOSINGDATE response field 131
COMPLETETYPE request field 27
CONFIRMATIONCODE response field 26
COUNTRYCODE 123, 166, 169
COUNTRYCODE request field 43, 54, 143, 144, 161,
178
COUNTRYCODE response field 26, 81
CouponAmount response field 130
CouponAmountCurrency 130
CouponID 130
Create Billing Agreement request fields 161
Create Billing Agreement response fields 162
Create Recurring Payments Profile request fields 137
Create Recurring Payments Profile response fields 145
CreateBillingAgreement API operation 161
CreateBillingAgreement request message 161
CreateBillingAgreement response message 162
CreateRecurringPaymentsProfile API operation 137
CreateRecurringPaymentsProfile request message 137
CreateRecurringPaymentsProfile response
message 145

298

Credit Card Details request fields 42, 52, 142, 159, 177
Credit Card Details response fields 152
CREDITCARDTYPE request field 42, 52, 142, 159,
177
CREDITCARDTYPE response field 152
currency codes 275, 276
CURRENCYCODE request field 27, 33, 36, 43, 52, 55,
58, 67, 94, 135, 140, 159, 173, 185, 188, 190
CURRENCYCODE response field 54, 83, 109, 126,
151, 180
CUSTOM request field 45, 69, 97, 174
CUSTOM response field 79, 85, 129
CUSTOMERSERVICENUMBER request field 64
CVV2 request field 42, 52, 142, 160, 177
CVV2 response codes 279
CVV2MATCH response field 48, 178
Czech Koruna 275, 276
CZK 275, 276

D
Danish Krone 275, 276
DESC request field 45, 69, 96, 138, 156, 174
DESC response field 85, 147
Discover AVS response codes 277
Discover CVV2 response codes 279
DKK 275, 276
Do Authorization request fields 32
Do Authorization response fields 33
Do Capture request fields 27
Do Capture response fields 29
Do Direct Payment request field 41
Do Direct Payment response fields 48
Do ExpressCheckout Payment request fields 92
Do ExpressCheckout Payment response fields 105
Do NonReferenced Credit request fields 51
Do NonReferenced Credit response fields 54
Do Reauthorization request fields 36
Do Reauthorization response fields 37
Do Reference Transaction request fields 171
Do Reference Transaction response fields 178
Do Void request fields 39
Do Void response fields 39
DoAuthorization API operation 32
DoAuthorization request message 32
DoAuthorization response message 33
DoCapture API operation 27

August 2012

Name-Value Pair API Developer Guide

Index

DoCapture request message 27
DoCapture response message 29
DoDirectPayment API operation 41
DoDirectPayment request message 41
DoDirectPayment response message 48
DoExpressCheckoutPayment API operation 92
DoExpressCheckoutPayment request message 92
DoExpressCheckoutPayment response message 105
DoNonReferencedCredit API operation 51
DoNonReferencedCredit request message 51
DoNonReferencedCredit response message 54
DoReauthorization API operation 36
DoReauthorization request message 36
DoReauthorization response message 37
DoReferenceTransaction API operation 171
DoReferenceTransaction request message 171
DoReferenceTransaction response message 178
DoVoid API operation 39
DoVoid request message 39
DoVoid response message 39

E
Ebay Item Payment Details Item request fields 46, 75,
103, 176
Ebay Item Payment Details Item response fields 89
EBAYITEMAUCTIONTXNID response field 113
EBAYITEMAUCTIONTXNIDn response field 90
EBAYITEMCARTIDn response field 90
EBAYITEMNUMBERn response field 89
EBAYITEMORDERIDn response field 90
EbayItemTxnId response field 130
ECI3DS request field 48
ECISUBMITTED3DS response field 50
EMAIL request field 25, 42, 53, 63, 143, 160, 177, 189
EMAIL response field 80, 123, 152, 166, 169
EMAILSUBJECT request field 135
ENDDATE request field 189
error codes 193
error responses 23
EUR 275, 276
Euro 275, 276
EXCHANGERATE response field 110, 126, 181
EXPDATE request field 42, 52, 142, 160, 177
EXPDATE response field 152
ExpressCheckout API Operatons 55

Name-Value Pair API Developer Guide

F
FAILEDINITAMTACTION request field 141
FAILEDPAYMENTCOUNT response field 151
FEEAMT response field 109, 126, 180
FEEREFUNDAMT response field 187
FINALPAYMENTDUEDATE response field 147
FIRSTNAME request field 42, 53, 143, 160, 177, 191
FIRSTNAME respo n se field 152
FIRSTNAME response field 81, 124, 167, 169
Forint 275, 276
Funding Source Details request fields 76

G
GBP 275, 276
Get Balance request fields 117
Get Balance response fields 117
Get Billing Agreement Customer Details request
fields 166
Get ExpressCheckout Details request fields 78
Get ExpressCheckout Details response fields 79
Get Pal Details request fields 119
Get Pal Details response fields 119
Get Recurring Payments Profile Details request
fields 146
Get Recurring Payments Profile Details response
fields 146
Get Transaction Details request fields 121
Get Transaction Details response fields 121
GetBalance API operation 117
GetBalance request message 117
GetBalance response message 117
GetBillingAgreementCustomerDetails API
operation 166
GetBillingAgreementCustomerDetails request
message 166
GetBillingAgreementCustomerDetails response
message 166
GetExpressCheckoutDetails API operation 78
GetExpressCheckoutDetails request message 78
GetExpressCheckoutDetails response message 79
GetPalDetails API operation 119
GetPalDetails request message 119
GetPalDetails response message 119
GetRecurringPaymentsProfileDetails API
operation 146

August 2012

299

Index

INVNUM response field 79, 86, 129
IPADDRESS request field 41, 171
Israeli Sheqel 275
ISSUENUMBER request field 42, 52, 142, 160, 177
ISSUENUMBER response field 152
ITE MAMT request field 44
ITEMAMT request field 67, 95, 173, 289
ITEMAMT response field 83

GetRecurringPaymentsProfileDetails request
message 146
GetRecurringPaymentsProfileDetails response
message 146
GetTransactionDetails API operation 121
GetTransactionDetails request message 121
GetTransactionDetails response message 121
GIFTMESSAGE request field 93
GIFTMESSAGE response field 80, 122
GIFTMESSAGEENABLE request field 64
GIFTRECEIPTENABLE request field 64, 93
GIFTRECEIPTENABLE response field 80, 122
GIFTWRAPAMOUNT request field 65, 93
GIFTWRAPAMOUNT response field 80, 122
GIFTWRAPENABLE request field 64
GIFTWRAPNAME request field 64, 93
GIFTWRAPNAME response field 80, 122
GIROPAYCANCELURL request field 64
GIROPAYSUCCESSURL request field 64
GROSSREFUNDAMT response field 187

J
Japanese Yen 275, 276
JPY 275, 276

K
Koruna 275, 276
Krona 275, 276
Krone 275, 276

H
HANDLINGAMT requ e st f i eld 174
HANDLINGAMT request field 44, 69, 96
HANDLINGAMT response field 85
HDRBACKCOLOR request field 63, 164
HDRBORDERCOLOR request field 63, 164
HDRIMG request field 63, 164
HKD 275
Hong Kong Dollar 275
HUF 275, 276
Hungarian Forint 275, 276

I
ILS 275
INITAMT request field 141
InstrumentDetails response field 114
INSURANCEAMT request field 44, 68, 95
INSURANCEAMT response field 84
INSURANCEOPTIONOFFERED request field 68, 96
INSURANCEOPTIONOFFERED response field 84
INSURANCEOPTIONSELECTED request field 104
INSURANCEOPTIONSELECTED response field 90,
115, 122
INVNUM request field 28, 45, 70, 174, 185, 189

300

L_AMT request field 46, 175, 288
L_AMTn request field 57, 72, 100, 290
L_AMTn response field 87, 117, 130, 192
L_BILLINGAGREEMENTCUSTOMn request
field 77, 165, 168
L_BILLINGAGREEMENTCUSTOMn response
field 169
L_BILLINGAGREEMENTDESCRIPTIONn request
field 77, 165, 168
L_BILLINGAGREEMENTDESCRIPTIONn response
field 168
L_BILLINGAGREEMENTMAXn response field 169
L_BILLINGTYPEn request field 77, 164
L_BILLINGTYPEn response field 168
L_COUPONAMOUNTCurrencyn response field 130
L_COUPONAMOUNTn response field 130
L_COUPONIDn response field 130
L_CURRENCYCODEn response field 117, 192
L_DESCn request field 46, 57, 72, 100, 175, 290
L_DESCn response field 87, 130
L_EBAYITEMAUCTIONTXNIDn request field 46,
75, 103, 176
L_EBAYITEMCARTIDn request field 75, 104
L_EBAYITEMNUMBERn request field 46, 75, 103,
176

August 2012

Name-Value Pair API Developer Guide

Index

L_EBAYITEMORDERIDn request field 47, 75, 103,
176
L_EBAYITEMTXNID response field 130
L_EMAILn response field 192
L_FEEAMTn response field 192
L_FMFfilterIDn response field 49, 106, 114, 179
L_FMFfilterNAM E n response field 114
L_FMFfilterNAMEn response field 49, 106, 179
L_INSURANCEAMOUNT response field 59
L_ITEMCATEGORYn 175, 288
L_ITEMHEIGHTUNITn request field 57, 74, 102
L_ITEMHEIGHTUNITn response field 89
L_ITEMHEIGHTVALUEn request field 57, 74, 102
L_ITEMHEIGHTVALUEn response field 89
L_ITEMLENGHTUNITn request field 73, 102
L_ITEMLENGTHUNITn request field 57
L_ITEMLENGTHUNITn response field 88
L_ITEMLENGTHVALUEn request field 57, 73, 102
L_ITEMLENGTHVALUEn response field 88
L_ITEMURLn request field 74, 102
L_ITEMWEIGHTUNITn request field 57, 73, 101
L_ITEMWEIGHTUNITn response field 88
L_ITEMWEIGHTVALUEn request field 57, 73, 101
L_ITEMWEIGHTVALUEn response field 88
L_ITEMWIDTHUNITn request field 57, 73, 102
L_ITEMWIDTHUNITn response field 89
L_ITEMWIDTHVALUEn request field 57, 73, 102
L_ITEMWIDTHVALUEn response field 89
L_LOYALTYCARDDISCOUNTAMOUNTn response
field 130
L_LOYALTYCARDDISCOUNTCURRENCYn
response field 130
L_NAMEn request field 46, 56, 71, 100, 175, 288, 290
L_NAMEn response field 87, 192
L_NETAMTn response field 192
L_NUMBER request field 46, 176
L_NUMBERn request field 56, 72, 101
L_NUMBERn response field 88, 130
L_OPTIONSNAMEn response field 131
L_OPTIONSVALUEn response field 131
L_PAYMENTINFO_n_FMFfilterIDm response
field 114
L_PAYMENTINFO_n_FMFfilterNAMEm response
field 114
L_PAYMENTRE
QUEST_n_ITEMWEIGHTVALUEm response
field 88

Name-Value Pair API Developer Guide

L_PAYMENTREQUESST_n_EBAYITEMAUCTIONT
XNIDm request field 75, 103
L_PAYMENTREQUEST_n_AMTm request field 72,
100, 145, 287, 290
L_PAYMENTREQUEST_n_AMTm response field 87
L_PAYMENTREQUEST_n_DESCm request field 72,
100, 144, 287, 290
L_PAYMENTREQUEST_n_DESCm response field 87
L_PAYMENTREQUEST_n_EBAYCARTIDm request
field 75, 104
L_PAYMENTREQUEST_n_EBAYITEMAUCTIONT
XNIDm response field 90
L_PAYMENTREQUEST_n_EBAYITEMCARTIDm
response field 90
L_PAYMENTREQUEST_n_EBAYITEMNUMBERm
request field 75, 103
L_PAYMENTREQUEST_n_EBAYITEMNUMBERm
response field 89
L_PAYMENTREQUEST_n_EBAYITEMORDERIDm
request field 75, 103
L_PAYMENTREQUEST_n_EBAYITEMORDERIDm
response field 90
L_PAYMENTREQUEST_n_ITEMCATEGORYm
request field 74, 103, 144, 287
L_PAYMENTREQUEST_n_ITEMCATEGORYm
response field 89
L_PAYMENTREQUEST_n_ITEMHEIGHTUNITm
request field 74, 102
L_PAYMENTREQUEST_n_ITEMHEIGHTUNITm
response field 89
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUEm
request field 74, 102
L_PAYMENTREQUEST_n_ITEMHEIGHTVALUEm
response field 89
L_PAYMENTREQUEST_n_ITEMLENGTHUNITm
request field 73, 102
L_PAYMENTREQUEST_n_ITEMLENGTHUNITm
response field 88
L_PAYMENTREQUEST_n_ITEMLENGTHVALUEm
requ est field 73, 102
L_PAYMENTREQUEST_n_ITEMLENGTHVALUEm
response field 88
L_PAYMENTREQUEST_n_ITEMURLm request
field 74, 102
L_PAYMENTREQUEST_n_ITEMWEIGHTUNITm
request field 73, 101
L_PAYMENTREQUEST_n_ITEMWEIGHTUNITm
response field 88
L_PAYMENTREQUEST_n_ITEMWEIGHTVALUEm
request field 73, 101

August 2012

301

Index

L_PAYMENTREQUEST_n_ITEMWIDTHUNITm
request field 73, 102
L_PAYMENTREQUEST_n_ITEMWIDTHUNITm
response field 89
L_PAYMENTREQUEST_n_ITEMWIDTHVALUEm
request field 73, 102
L_PAYMENTREQUEST_n_ITEMWIDTHVALUEm
response field 89
L_PAYMENTREQUEST_n_NAMEm request field 71,
100, 144, 287, 290
L_PAYMENTREQUEST_n_NAMEm response
field 87
L_PAYMENTREQUEST_n_NU MBERm response
field 88
L_PAYMENTREQUEST_n_NUMBERm request
field 72, 101, 145, 287
L_PAYMENTREQUEST_n_QTYm request field 72,
101, 145, 288, 290
L_PAYMENTREQUEST_n_QTYm response field 88
L_PAYMENTREQUEST_n_TAXAMTm request
field 73, 88, 101, 145, 288
L_PAYMENTTYPEn request field 77, 165
L_QTY request field 46, 176, 289
L_QTYn request field 57, 72, 101, 290
L_QTYn response field 88, 130
L_SHIPPINGOPTIONAMOUNT response field 58
L_SHIPPINGOPTIONAMOUNTn request field 76
L_SHIPPINGOPTIONAMOUNTn response field 122
L_SHIPPINGOPTIONISDEFAULT response field 58
L_SHIPPINGOPTIONISDEFAULTn request field 76
L_SHIPPINGOPTIONISDEFAULTn response
field 122
L_SHIPPINGOPTIONLABEL response field 58
L_SHIPPINGOPTIONNAME response field 58
L_SHIPPINGOPTIONNAMEn request field 76
L_SHIPPINGOPTIONNAMEn response field 122
L_STATUSn response field 192
L_SURVEYCHOICEn request field 65
L_TAXAMT request fi eld 46
L_TAXAMT request field 176
L_TAXAMT response field 58
L_TAXAMTn request field 73, 88, 101
L_TIMESTAMPn response field 192
L_TIMEZONEn response field 192
L_TRANSACTIONIDn response field 192
L_TYPEn response field 192
LANDINGPAGE request field 64
LASTNAME request field 43, 53, 143, 160, 178, 191
LASTNAME response field 81, 124, 152, 167, 170
302

LASTPAYMENTAMT response field 151
LASTPAYMENTDATE response field 151
LOCALE response field 120
LOCALECODE request field 56, 62, 163
LoyaltyCardDiscountAmount 130
LoyaltyCardDiscountCurrency 130

M
Maestro AVS response codes 278
Maestro CVV2 response codes 279
Malaysian Ringgit 275
Manage Pending Transaction Status request fields 133
Manage Pending Transaction Status response fields 134
Manage Recurring Payments Profile Status request
fields 154
Manage Recurring Payments Profile Status response
fields 154
ManagePendingTransactionStatus API operation 133
ManagePendingTransactionStatus request message 133
ManagePendingTransactionStatus response
message 134
ManageRecurringPaymentsProfileStatus API
operation 154
ManageRecurringPaymentsProfileStatus request
message 154
ManageRecurringPaymentsProfileStatus response
message 154
Mass Payment request fields 135
MassPay API operation 135
MassPay request message 135
MassPay response fields 135
MassPay response message 135
MasterCard AVS response codes 277
MasterCard CVV2 response codes 279
MAXAMT request field 60
MAXFAILEDPAYMENTS request field 138, 157
MAXFAILEDPAYMENTS response field 147
MERCHANTSTOREDETAILS request field 186
METHOD req uest field 121
METHOD request field 25, 27, 32, 36, 39, 41, 51, 55,
59, 78, 92, 117, 119, 133, 135, 137, 146, 154, 155,
156, 161, 162, 164, 166, 168, 171, 185, 189
METHOD response field 58
Mexican Peso 275
MIDDLENAME request field 53, 143, 191
MIDDLENAME response field 81, 124, 167, 170
MPIVENDOR3DS request field 47

August 2012

Name-Value Pair API Developer Guide

Index

MSGSUBID request field 28, 29, 33, 172, 179, 186,
188
MULTIITEM response field 131
MXN 275
MYR 275

N
NETAMT request field 51
NETREFUNDAMT response field 187
New Zealand Dollar 275, 276
NEXTBILLINGDATE response field 151
NO_SHIPPING_OPTION_DETAILS response
field 59
NOK 275, 276
Norwegian Krone 275, 276
NOSHIPPING request field 61
NOTE request field 28, 39, 52, 154, 155, 156
NOTE response field 79, 105, 129
NOTETEXT request field 70, 97
NOTETEXT response field 86
NOTETOBUYER request field 65
NOTIFY URL request field 97
NOTIFYURL request field 45, 70, 175
NOTIFYURL response field 86
NUMCYCLESREMAINING response field 151
NUMCYCYLESCOMPLETED response field 151
NVP format 17
NZD 275, 276

O
OfferDetails response field 114
OFFERINSURANCEOPTION response field 58, 59
ORDERTIME response field 109, 125, 180
OUTSTANDINGAMT request field 157
OUTSTANDINGBALANCE response field 151

P
PAGESTYLE request field 62, 163
PAL response field 119
PARENTTRANSACTIONID re sponse field 125, 180
PAY MENTREQUEST_n_DESC request field 96
Payer Information request fields 42, 53, 143, 160, 177
Payer Information response fields 80, 123, 152, 166,
169

Name-Value Pair API Developer Guide

Payer Name request fields 53, 143, 191
Payer Name response fields 81, 124, 167, 169
PAYERBUSINESS response field 123, 166, 169
PAYERID req uest field 143
PAYERID request field 93
PAYERID response field 80, 123, 166, 169
PAYERSTATUS request field 143
PAYERSTATUS response field 80, 123, 166, 169
PAYFLOWCOLOR request field 63, 164
PAYME
NREQUEST_n_INSURANCEOPTIONOFFERE
D response field 84
Payment Details Item request fields 46, 71, 100, 144,
175, 287, 288, 290
Payment Details Item response fields 87
Payment Details request fields 43, 67, 94, 173
Payment Details response fields 83
Payment Error Type response fields 91, 115
Payment Information response fields 108, 125, 179
Payment Item Information response fields 129
Payment Request Info Type response fields 91
PAYMENTACTION reque st field 63
PAYMENTACTION request field 41, 71, 93, 98, 171,
289
PAYMENTINFO_n_AMT response field 109
PAYMENTINFO_n_CURRENCYCODE response
field 109
PAYMENTINFO_n_EBAYITEMAUCTIONTXNID
response field 113
PAYMENTINFO_n_EXCHANGERATE response
field 110
PAYMENTINFO_n_FEEAMT response field 109
PAYMENTINFO_n_HOLDDECISION response
field 112
PAYMENTINFO_n_ORDERTIME response field 109
PAYMENTINFO_n_PAYMENTSTATUS response
field 110
PAYMENTINFO_n_PAYMENTTYPE response
field 108
PAYMENTINFO_n_PENDINGREASON response
field 111
PAYMENTINFO_n_PROTECTIONELIGIBILITY
response field 112
PAYMENTINFO_n_PROTECTIONELIGIBILITYTYP
E response field 113
PAYMENTINFO_n_REASONCODE response
field 112
PAYMENTINFO_n_TAXAMT response field 109

August 2012

303

Index

PAYMENTINFO_n_TRANSACTIONID response
field 108, 109
PAYMENTINFO_n_TRANSACTIONTYPE response
field 108
PaymentItemType response fields 130
PaymentPeriod.Amount request field 140
PaymentReason request field 65, 172
PAYMENTREQUEST_n_ACK response field 91, 115
PAYMENTREQUEST_n_ADDRESSSTATUS
response field 82
PAYMENTREQUEST_n_AL LOWE
DPAYMENTMETHOD response field 86
PAYMENTREQUEST_n_ALLOWEDPA
YMENTMETHOD request field 98
PAYMENTREQUEST_n_ALLOWEDPAYMENTMET
HOD request field 70
PAYMENTREQUEST_n_AMT request field 67, 94
PAYMENTREQUEST_n_AMT response field 83
PAYMENTREQUEST_n_CURRENCYCODE request
field 67, 94
PAYMENTREQUEST_n_CURRENCYCODE
response field 83
PAYMENTREQUEST_n_CUSTOM request field 69,
97
PAYMENTREQUEST_n_CUSTOM response field 85
PAYMENTREQUEST_n_DESC request field 69
PAYMENTREQUEST_n_DESC response field 85
PAYMENTREQUEST_n_ERRORCODE response
field 91, 115
PAYMENTREQUEST_n_HANDLINGAMT request
field 69, 96
PAYMENTREQUEST_n_HANDLINGAMT response
field 85
PAYMENTREQUEST_n_INSURANCEAMT request
field 68, 95
PAYMENTREQUEST_n_INSURANCEAMT response
field 84
PAYMENTREQUEST_n_INSURANCEOPTIONOFFE
RED request field 68, 96
PAYMENTREQUEST_n_INVNUM request field 70,
97
PAYMENTREQUEST_n_INVNUM response field 86
PAYMENTREQUEST_n_ITEMAMT request field 67,
95, 289
PAYMENTREQUEST_n_ITEMAMT respo nse
field 83
PAYMENTREQUEST_n_LONGMESSAGE response
field 91, 115
PAYMENTREQUEST_n_NOTETEXT request
field 70, 97

304

PAYMENTREQUEST_n_NOTETEXT response
field 86
PAYMENTREQUEST_n_NOTIFYURL request
field 70, 97
PAYMENTREQUEST_n_NOTIFYURL response
field 86
PAYMENTREQUEST_n_PAYMENTACTION request
field 71, 98, 289
PAYMENTREQUEST_n_PAYMENTREQUESTID
request field 71, 98
PAYMENTREQUEST_n_PAYMENTREQUESTID
response field 87, 91, 113
PAYMENTREQUEST_n_SECUREME R
CHANTACCOUNT ID response field 116
PAYMENTREQUEST_n_SELLERID request
field 104
PAYMENTREQUEST_n_SELLERPAYPALACCOUN
TID request field 74
PAYMENTREQUEST_n_SELLERPAYPALACCOUN
TID response field 91, 116
PAYMENTREQUEST_n_SELLERREGISTRATIOND
ATE request field 105
PAYMENTREQUEST_n_SELLERUSERNAME
request field 105
PAYMENTREQUEST_n_SEVERITYCODE response
field 91, 115
PAYMENTREQUEST_n_SHIPDISCAMT request
field 68, 95
PAYMENTREQUEST_n_SHIPDISCAMT response
field 84
PAYMENTREQUEST_n_SHIPPINGAMT request
field 68, 95
PAYMENTREQUEST_n_SHIPPINGAMT response
field 84
PAYMENTREQUEST_n_SHIPTOCITY request
field 66, 99
PAYMENTREQUEST_n_SHIPTOCITY response
field 82
PAYMENTREQUEST_n_SHIPTOCOUNTRY request
field 66, 99
PAYMENTREQUEST_n_SHIPTOCOUNTRY
response field 82
PAYMENTREQUEST_n_SHIPTONAME request
field 66, 99
PAYMENTREQUEST_n_SHIPTONAME response
field 81
PAYMENTREQUEST_n_SHIPTOPHONENUM
request field 67, 100
PAYMENTREQUEST_n_SHIPTOPHONENUM
response field 82

August 2012

Name-Value Pair API Developer Guide

Index

PAYMENTREQUEST_n_SHIPTOSTATE request
field 66, 99
PAYMENTREQUEST_n_SHIPTOSTATE response
field 82
PAYMENTREQUEST_n_SHIPTOSTREET request
field 66, 99
PAYMENTREQUEST_n_SHIPTOSTREET response
field 81
PAYMENTREQUEST_n_SHIPTOSTREET2 request
field 66, 99
PAYMENTREQUEST_n_SHIPTOSTREET2 response
field 81
PAYMENTREQUEST_n_SHIPTOZIP request
field 66, 99
PAYMENTREQUEST_n_SHIPTOZIP response
field 82
PAYMENTREQUEST_n_SHORTMESSAGE response
field 91, 115
PAYMENTREQUEST_n_SOFTDESCRIPTOR request
field 97
PAYMENTREQUEST_n_TAXAMT request field 69,
96
PAYMENTREQUEST_n_TAXAMT response field 85
PAYMENTREQUEST_n_TRANSACTIONID request
field 70
PAYMENTREQUEST_n_TRANSACTIONID response
field 86, 91
PAYMENTREQUESTID request field 71, 98
PAYMENTREQUESTID response fie ld 87
PAYMENTREQUESTID response field 113
PAYMENTREQUESTn_TRANSACTIONID request
field 98
PAYMENTSTATUS response field 34, 37, 110, 127,
181
PAYMENTTYPE response field 105, 108, 125, 180
PAYPALADJUSTMENT response field 79
PENDIN GREASON response field 128, 182
PENDINGREASON request field 188
PENDINGREASON response field 35, 38, 111
PERIOD response field 131
Peso 275
Philippine Peso 275
PHONENUM response field 79
PHP 275
PLN 275, 276
Polish Zloty 275, 276
Pound Sterling 275, 276
PR OTECTIONELIGIBILITY response field 129, 183
previous versions 281

Name-Value Pair API Developer Guide

PROFILEID request field 146, 154, 155, 156
ProfileID request field 191
PROFILEID response field 145, 146, 155, 161
ProfileID response field 154
PROFILEREFERENCE request field 138, 156
PROFILEREFERENCE response field 147
PROFILESTARTDATE request field 138, 157
PROFILESTARTDATE response field 147
PROTECTIONELIGIBILITY response field 35, 38,
112
PROTECTIONELIGIBILITYTYPE response field 36,
39, 129, 183

R
RE DIRECTREQUIRED response field 79
REASONCODE response field 112, 128, 182
RECEIPTID request field 189
RECEIPTID response field 125, 180
Receiver Information response fields 123
RECEIVER request field 189
RECEIVERBUSINESS response field 123
RECEIVEREMAIL response field 123
RECEIVERID response field 123
RECEIVERTYPE request field 135
Recurring Payments API Operations 137
Recurring Payments Profile Details request fields 138
Recurring Payments Profile Details response fields 147
Recurring Payments Summary Details response
fields 151
RECURRING request field 45, 175, 285
REDIRECTREQUIRED response field 105
Reference Transactions API Operations 137
REFERENCEID request field 168, 171
Refund Transaction request fields 185
Refund Transaction response fields 187
REFUNDADVICE request field 186
REFUNDINFO request field 188
REFUNDITEMDETAILS request field 186
REFUNDSOURCE request field 186
REFUNDSTATUS request field 188
RefundTransaction API operation 185
RefundTransaction request message 185
RefundTransaction response message 187
REFUNDTRANSACTIONID response field 187
REFUNDTYPE request field 185, 284
REGULARAMT response field 150

August 2012

305

Index

REGULARBILLINGFREQUENCY response field 149
REGULARBILLINGPERIOD response field 149
REGULARCURRENCYCODE response field 151
REGULARSHIPPINGAMT response field 150
REGULARTAXAMT response field 151
REGULARTOTALBILLINGCYCLES response
field 149
REQCONFIRMSHIPPING request field 60, 171
RET URNURL request field 60
RETRYUNTIL request field 186
RETURNALLCURRENCIES request field 117
RETURNFMFDETAILS request field 41, 93, 171
RETURNURL request field 162

S
SALESTAX response field 129
SALUTATION request field 53, 143, 191
SALUTATION response field 81, 124, 167, 169
Schedule Details request fields 138
SEK 275, 276
Seller Details request fields 104
SELLERID request field 104
SELLERREGISTRATIONDATE re quest field 105
SELLERUSERNAME request field 105
Set Customer Billing Agreement request fields 162
Set Customer Billing Agreement response fields 165
Set ExpressCheckout request fields 59
Set ExpressCheckout response fields 78
SetCustomerBillingAgreement API operation 162
SetCustomerBillingAgreement request message 162
SetCustomerBillingAgreement response message 165
SetExpressCheckout API operation 59
SetExpressCheckout request message 59
SetExpressCheckout response message 78
SETTLEAMT response field 109, 126, 181
SGD 275, 276
Sheqel 275
Ship To Address response fields 148, 167
SHIPDISCAMT request field 44
Shipping Options request fields 76
SHIPPINGAMT reque st field 174
SHIPPINGAMT request field 44, 51, 68, 95, 157, 159
SHIPPINGAMT response field 84, 150
SHIPPINGCALCULATIONMODE response field 90,
115, 121
SHIPPINGDISCAMT r esponse field 84

306

SHIPPINGDISCAMT request field 68, 95
SHIPPINGOPTIONAMOUNT request field 104
SHIPPINGOPTIONAMOUNT response field 90, 115
SHIPPINGOPTIONISDEFAULT request field 104
SHIPPINGOPTIONISDEFAULT response field 90,
115
SHIPPINGOPTIONNAME request field 104
SHIPPINGOPTIONNAME response field 90, 115
ShipTo Address request fields 47, 66, 99, 141, 157, 172
ShipTo Address response fields 81
SHIPTOCITY request fie ld 57
SHIPTOCITY request field 47, 66, 99, 141, 158, 173
SHIPTOCITY response field 82, 124, 148, 153, 167
SHIPTOCOUNTRY request field 47, 57, 66, 99, 142,
158, 173
SHIPTOCOUNTRY response field 82
SHIPTOCOUNTRYCODE response field 125, 148,
153, 167
SHIPTONAME request field 47, 66, 99, 141, 157, 172
SHIPTONAME response field 81, 124, 148, 153, 167
SHIPTOPHONENUM request field 43, 47, 54, 67, 100,
142, 144, 158, 161, 173, 178
SHIPTOPHONENUM response field 82, 125, 153
SHIPTOSTATE request field 47, 57, 66, 99, 141, 158,
173
SHIPTOSTATE response field 82, 124, 148, 153, 167
SHIPTOSTRE ET2 resp onse field 124, 153
SHIPTOSTREET request field 47, 57, 66, 99, 141, 157,
173
SHIPTOSTREET response f ield 148, 167
SHIPTOSTREET response field 81, 124, 153
SHIPTOSTREET2 request field 47, 57, 66, 99, 141,
158, 173
SHIPTOSTREET2 response field 81, 148, 167
SHIPTOZIP request field 47, 57, 66, 99, 142, 158, 173
SHIPTOZIP response field 82, 124, 148, 153, 167
Singapore Dollar 275, 276
SOFTDESCRIPTOR request field 28, 97, 172
SOLUTIONTYPE request field 63
STARTDATE request field 42, 52, 142, 160, 177, 189,
190
STARTDATE response field 152
state and proivince codes 271
STATE request field 43, 53, 144, 161, 178
STATUS request field 191
STATUS response field 134, 146
StoreId 113, 129, 183
STOREID request field 29, 186, 283, 284

August 2012

Name-Value Pair API Developer Guide

Index

STREET request field 25, 43, 53, 143, 160, 178
STREET2 request field 43, 53, 143, 160, 178
STREETMATCH response field 26
SUBSCRIBERNAME request field 138, 156
SUBSCRIBERNAME response field 147
Subscription Terms response fields 131
SUCCESSPAGEREDIRECTREQUESTED response
field 106
SUFFIX request field 53, 143, 191
SUFFIX response field 81, 124, 167, 170
SURVEYCHOICESELECTED request field 93
SURVEYCHOICESELECTED response field 80, 123
SURVEYENABLE request field 65
SURVEYQUESTION request field 65, 93
SURVEYQUESTION response field 80, 122
Swedish Krona 275, 276
Swiss Franc 275, 276

T
Taiwan New Dollar 275
TAXAMT request field 44, 51, 69, 96, 157, 159, 174
TAXAMT response fie ld 109
TAXAMT response field 85, 126, 150, 181
TAXIDDETAILS request field 78
TAXIDDETAILS response field 92
TaxIdDetailsType request fields 78
TaxIdDetailsType response fields 92
TAXIDTYPE request field 78
TAXIDTYPE response field 92
TerminalId 113, 129, 183
TERMINALID response field 29, 187, 283, 284
Thai Baht 276
THB 276
TOKEN request field 55, 79, 92, 137, 161, 166
TOKEN response field 26, 78, 79, 105, 165
TOTALBILLINGCYCLES request field 139, 158
TOTALBILLINGCYCLES response field 149
TOTALREFUNDEDAMT response field 187
TOTALTYPE request field 65
Transaction Search request fields 189
Transaction Search response fields 192
TRANSACTIONCLASS request field 190
TRANSACTIONENTITY request field 33
TRANSACTIONID request field 32, 70, 98, 121, 133,
185, 189

Name-Value Pair API Developer Guide

TRANSACTIONID response field 33, 48, 54, 86, 108,
125, 134, 179
TransactionSearch API operation 189
TransactionSearch request message 189
TransactionSearch response message 192
TRANSACTIONTYPE response field 108, 125, 180
TRIALAMT request field 140, 159
TRIALBILLINGFREQUENCY request field 140
TRIALBILLINGPERIOD request field 139
TRIALTOTALBILLINGCYCLES request field 140,
158
TRY 276
Turkish Lira 276
TWD 275

U
U.S. Dollar 276
Update Recurring Payments Profile request fields 156
Update Recurring Payments Profile response fields 161
UpdateRecurringPaymentsProfile API operation 156
UpdateRecurringPaymentsProfile request message 156
UpdateRecurringPaymentsProfile response
message 161
URL-encoding 20
USD 276
User Selected Options response fields 90, 115

V
Visa AVS response codes 277
Visa CVV2 response codes 279
VPAS response field 50

X
XID request field 48

Y
Yen 275, 276

Z
ZIP request field 25, 43, 54, 144, 161, 178
ZIPMATCH response field 26
Zloty 275, 276

August 2012

307

Index

308

August 2012

Name-Value Pair API Developer Guide

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.6
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:08:04
Producer                        : Acrobat Distiller 9.0.0 (Windows)
Creator Tool                    : FrameMaker 9.0
Modify Date                     : 2012:08:09 22:52:57-05:00
Create Date                     : 2012:08:09 22:02:28Z
Metadata Date                   : 2012:08:09 22:52:57-05:00
Format                          : application/pdf
Title                           : PayPal Name-Value Pair API Developer Guide
Creator                         : PayPal, Inc.
Document ID                     : uuid:04a2de93-b7da-4563-a228-abb82438185a
Instance ID                     : uuid:07a0e7cf-a62e-4b74-9fc9-6cb06d7498a3
Page Mode                       : UseOutlines
Page Count                      : 308
Author                          : PayPal, Inc.

EXIF Metadata provided by EXIF.tools

Paypal Name Value Pair Api 2012 Developers Guide Developer

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

Navigation menu

Versions of this User Manual:

Views

Navigation