PayPal Name-Value Pair API - 2012 Developer's Guide
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 3
Contents
Address Verify Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Chapter 3 Authorization and Capture API Operation Reference . . . .27
DoCapture API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
DoCapture Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
DoCapture Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
DoAuthorization API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
DoAuthorization Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
DoAuthorization Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . 33
DoReauthorization API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
DoReauthorization Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . 36
DoReauthorization Response Message . . . . . . . . . . . . . . . . . . . . . . . . . 37
DoVoid API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
DoVoid Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
DoVoid Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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
4 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 5
Contents
Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Payment Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Payment Item Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Payment Item Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
Auction Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Subscription Terms Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Chapter 10 ManagePendingTransactionStatus API Operation . . . . . 133
ManagePendingTransactionStatus Request Message. . . . . . . . . . . . . . . . . . . .133
ManagePendingTransactionStatus Request Fields . . . . . . . . . . . . . . . . . . .133
ManagePendingTransactionStatus Response Message . . . . . . . . . . . . . . . . . .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
6 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 7
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
8 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 9
Contents
10 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 11
What’s New in Version 93.0
12 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 13
Documentation Feedback
14 August 2012 Name-Value Pair API Developer Guide
PayPal Name-Value Pair API
1
Basics
The Name-Value Pair (NVP) API provides parameter-based association between request and
response fields of a message and their values. The request message is sent from your website
by the API, and a response message is returned by PayPal using a client-server model in which
your site is a client of the PayPal server.
NOTE: The PayFlow API also uses name-value pairs to provide parameter-based association
between request and response fields of a message and their values; however, the
PayFlow API is not the same as the NVP API; for more information about the
PayFlow API, see
PayPal API Client-Server Architecture
The PayPal API uses a client-server model in which your website is a client of the PayPal
server.
Gateway Developer Guide and Reference.
A page on your website initiates an action on a PayPal API server by sending a request to the
server. The PayPal server responds with a confirmation that the requested action was taken or
indicates that an error occurred. The response might also contain additional information
related to the request. The following diagram shows the basic request-response mechanism.
For example, you might want to obtain the buyer’s shipping address from PayPal. You can
initiate a request specifying an API operation to obtain buyer details. The response from the
PayPal API server contains information about whether the request was successful. If the
operation succeeds, the response contains the requested information. In this case, the response
contains the buyer’s shipping address. If the operation fails, the response contains one or more
error messages.
Related information:
Creating an NVP Request
Responding to an NVP Response
Name-Value Pair API Developer Guide August 2012 15
PayPal Name-Value Pair API Basics
1
PayPal API Client-Server Architecture
PayPal Name-Value Pair API Requests and Responses
To perform a PayPal NVP API operation, you send an NVP-formatted request to a PayPal
NVP server and interpret the response.
In the following diagram, your website generates a request. The request is executed on a
PayPal server and the response is returned to your site.
The request identifies:
The name of the API operation, specified by METHOD=name, to be performed and its
version
NOTE: After the METHOD parameter, you can specify the parameters in any order.
Credentials that identify the PayPal account making the request
Request-specific information that controls the API operation to be performed
A PayPal API server performs the operation and returns a response. The response contains:
An acknowledgement status that indicates whether the operation was a success or failure
and whether any warning messages were returned
Information that can be used by PayPal to track execution of the API operation
Response-specific information required to fulfill the request
UTF-8 Character Encoding
The PayPal API assumes that all data in requests is in Unicode, specifically, the Unicode (or
UCS) Transformation Format, 8-bit encoding form (UTF-8).
In responses, the API always returns data in UTF-8.
Multiple API Operations
Some of the features, such as Express Checkout, require you to call multiple API operations.
Typically, these features require you to:
16 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:
1
Token Usage
Typically, the API operation that sets up a redirection to PayPal returns a token. This token is
passed as a parameter in the redirect to PayPal. The token also might be required in related
API operations.
NVP Format
NVP is a way of specifying names and values in a string. NVP is the informal name for the
query in the URI specification. The NVP string is appended to the URL.
An NVP string conforms to the following guidelines:
The name is separated from the value by an equal sign (=). For example:
FIRSTNAME=Robert
Name-Value Pair API Developer Guide August 2012 17
PayPal Name-Value Pair API Basics
1
Creating an NVP Request
Name-value pairs are separated by an ampersand (&). For example:
FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore
The values for each value in an NVP string are URL-encoded.
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=
18 August 2012 Name-Value Pair API Developer Guide
version_number
PayPal Name-Value Pair API Basics
Specifying an API Credential Using Signatures
You must specify API credentials in each request to execute a PayPal API operation. You can
use either a signature or a certificate, but not both.
When you execute a PayPal API operation, you use credentials, such as a signature, to
authenticate that you are requesting the API operation. The following diagram shows the API
credentials part of an NVP request:
IMPORTANT: You must protect the values for USER, PWD, and SIGNATURE in your
implementation. Consider storing these values in a secure location other than
your web server document root and setting the file permissions so that only
the system user that executes your ecommerce application can access it.
Creating an NVP Request
1
To enable PayPal to authenticate your request:
1. Specify the API username associated with your account.
USER=
API_username
2. Specify the password associated with the API user name.
API_password
PWD=
3. If you are using an API signature and not an API certificate, specify the API signature
associated with the API username.
SIGNATURE=
API_signature
4. Optionally, you can specify the email address on file with PayPal of the third-party
merchant on whose behalf you are calling the API operation.
SUBJECT=
NOTE: Typically, a merchant grants third-party permissions to a shopping cart. The merchant
merchantEmailAddress
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 19
PayPal Name-Value Pair API Basics
1
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^ &..."
NOTE: This example does not establish a secure connection and should not be used live on
paypal.com.
URL Encoding
All requests to execute PayPal API operations sent using HTTP must be URL-encoded. The
encoding ensures that you can transmit special characters, characters that are not allowed in a
URL, and characters that have special meaning in a URL, such as the equal sign and
ampersand.
The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a
PayPal API server. You must encode all data sent using the HTTP protocol because data that is
not encoded could be misinterpreted as part of the HTTP protocol instead of part of the
request. Most programming languages provide a way to encode strings in this way. You should
consistently URL-encode the complete API request; otherwise, you may find that
unanticipated data causes an error.
NOTE: An HTTP form is automatically URL-encoded by most browsers.
For example, consider the following NVP string:
NAME=Robert Moore&COMPANY=R. H. Moore & Associates
It is encoded as follows:
NAME=Robert+Moore&COMPANY=R.+H.+Moore+%26+Associates
Use the following methods to URL-encode or URL-decode your NVP strings:
Encoding and decoding methods for URLs
Language Method
ASP.NET Encode System.Web.HttpUtility.UrlEncode(buffer,
Encoding.Default)
Decode System.Web.HttpUtility.UrlDecode(buffer,
Encoding.Default)
Classic ASP Encode Server.URLEncode
Decode No built-in function. Several implementation examples are available on the
Internet.
Java Encode java.net.URLEncoder.encode
Decode java.net.URLDecoder.decode
20 August 2012 Name-Value Pair API Developer Guide
PayPal Name-Value Pair API Basics
Language Method
PHP Encode urlencode()
Decode urldecode()
ColdFusion 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.
Executing NVP API Operations
1
NOTE: Not all lists follow the L_ prefix convention; however, all lists start with 0 as the first
element.
Executing NVP API Operations
You execute a PayPal NVP API operation by submitting an HTTPS POST request to a PayPal
API server, or by using cURL or another mechanism to provide secure access between the
buyer’s browser and the PayPal API server. For example, you might implement a system in
which the buyer’s browser remains a client of your server and your server becomes a client of
the PayPal API server.
Specifying a PayPal Server
You execute a PayPal API operation by submitting the request to a PayPal API server.
To execute a PayPal NVP API operation, submit the request to one of the following end
points:
Server end point Description
https://api3t.sandbox.paypal.com/nvp
Name-Value Pair API Developer Guide August 2012 21
Sandbox server for use with API signatures; use for testing your
API
PayPal Name-Value Pair API Basics
1
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
NOTE: You must use different API credentials for each server end point. Typically, you obtain
API credentials when you test in the Sandbox and then obtain another set of
credentials for the production server. You must change each API request to use the
new credentials when you go live.
Logging API Operations
You should log basic information from the request and response messages of each PayPal API
operation you execute. You must log the Correlation ID from the response message, which
identifies the API operation to PayPal and which must be provided to Merchant Technical
Support if you need their assistance with a specific transaction.
All responses to PayPal API operations contain information that may be useful for debugging
purposes. In addition to logging the Correlation ID from the response message, you can log
other information, such as the transaction ID and timestamp, to enable you to review a
transaction on the PayPal website or through the API. You could implement a scheme that logs
the entire request and response in a “verbose” mode; however, you should never log the
password from a request.
Responding to an NVP Response
The Name-Value Pair response consists of the answer to the request as well as common fields
that identify the API operation and how it was executed.
The following diagram shows fields in the response to a PayPal NVP API operation:
Related information:
PayPal API Client-Server Architecture
22 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.
1
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
Additional pass-through information may appear in the L_ERRORPARAMIDn and
L_ERRORPARAMVALUE
TIMESTAMP=2011%2d11%2d15T20%3a27%3a02Z&CORRELATIONID=5be53331d9700&ACK=Fail
ure&VERSION=78%2e0&BUILD=000000&L_ERRORCODE0=15005&L_SHORTMESSAGE0=Processo
r%20Decline&L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e&
L_SEVERITYCODE0=Error&L_ERRORP ARAMID0=ProcessorR esponse&L_ERRORPARAMV ALUE0=
0051&AMT=10%2e40&CURRENCYCODE=USD&AVSCODE=X&CVV2MATCH=M
ACK=
notSuccess&TIMESTAMP=date/timeOfResponse&
CORRELATIONID=
BUILD=
buildNumber&L_ERRORCODE0=errorCode&
L_SHORTMESSAGE0=
L_LONGMESSAGE0=
L_SEVERITYCODE0=
debuggingToken&VERSION=VersionNo&
shortMessage&
longMessage&
severityCode
n fields. Consider the following error response:
Multiple errors can be
returned. Each set of
errors has a different
numeric suffix, starting
with 0 and incremented
by one for each error.
Name-Value Pair API Developer Guide August 2012 23
PayPal Name-Value Pair API Basics
1
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.
NOTE: PayPal only passes selected values in the L_ERRORPARAMIDn and
L_ERRORPARAMVALUE
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
n fields.
24 August 2012 Name-Value Pair API Developer Guide
AddressVerify API Operation
2
The AddressVerify API operation confirms whether a postal address and postal code match
those of the specified PayPal account holder.
AddressVerify Request Message
Address Verify Request Fields
Field Description
METHOD (Required) Must be AddressVerify.
EMAIL (Required) Email address of a PayPal member to verify.
Character length and limitations: 255 single-byte characters maximum with the input
mask: ?@?.??
STREET (Required) First line of the billing or shipping postal address to verify. To pass
verification, the value of Street must match the first 3 single-byte characters of a
postal address on file for the PayPal member.
Character length and limitations: 35 single-byte characters maximum, including
alphanumeric plus - , . ‘ # \. Whitespace and case of input value are ignored.
ZIP (Required) Postal code to verify. To pass verification, the value of Zip must match
the first 5 single-byte characters of the postal code of the verified postal address for
the verified PayPal member.
Character length and limitations: 16 single-byte characters maximum. Whitespace
and case of input value are ignored.
Name-Value Pair API Developer Guide August 2012 25
AddressVerify API Operation
2
AddressVerify Response Message
AddressVerify Response Message
Address Verify Response Fields
Field Description
CONFIRMATIONCODE Indicates whether the address is a confirmed address on file at PayPal. It is one of the
following values:
None – The request value of the Email element does not match any email address
on file at PayPal.
Confirmed – If the response value of the StreetMatch element is Matched,
the entire postal address is confirmed.
Unconfirmed – PayPal responds that the postal address is unconfirmed.
NOTE: The values Confirmed and Unconfirmed both indicate that the member
email address passed verification.
STREETMATCH Indicates whether the street address matches address information on file at PayPal. It
is one of the following values:
None – The request value of the Email element does not match any email address
on file at PayPal. No comparison of other request values was made.
Matched – The request value of the Street element matches the first 3 single-byte
characters of a postal address on file for the PayPal member.
Unmatched – The request value of the Street element does not match any
postal address on file for the PayPal member.
ZIPMATCH Indicates whether the zip address matches address information on file at PayPal. It is
one of the following values:
None – The request value of the Street element was unmatched. No comparison
of the Zip element was made.
Matched – The request value of the Zip element matches the zip code of the
postal address on file for the PayPal member.
Unmatched – The request value of the Zip element does not match the zip code
of the postal address on file for the PayPal member.
COUNTRYCODE Country code (ISO 3166) on file for the PayPal email address.
Character length and limitations: 2 single-byte characters
TOKEN The token contains encrypted information about the member’s email address and
postal address. If you pass the value of the token in the HTML variable
address_api_token of Buy Now buttons, PayPal prevents the buyer from using
an email address or postal address other than those that PayPal verified with this API
call. The token is valid for 24 hours.
Character length and limitations: 94 single-byte characters
26 August 2012 Name-Value Pair API Developer Guide
Authorization and Capture API
3
Operation Reference
The Authorization and Capture API operations describe the PayPal API operations related to
delayed payment settlement:
DoCapture API Operation
Captures an authorized payment.
DoCapture Request Message
DoCapture Request Fields
Field Description
METHOD (Required) Must be DoCapture.
AUTHORIZATIONID (Required) Authorization identification number of the payment you want to capture.
This is the transaction ID returned from DoExpressCheckoutPayment,
DoDirectPayment, or CheckOut. For point-of-sale transactions, this is the
transaction ID returned by the CheckOut call when the payment action is
Authorization.
Character length and limitations: 19 single-byte characters maximum
AMT (Required) Amount to capture.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
CURRENCYCODE (Optional) A 3-character currency code (default is USD).
COMPLETETYPE (Required) Indicates whether or not this is your last capture. It is one of the following
values:
Complete – This is the last capture you intend to make.
NotComplete – You intend to make additional captures.
NOTE: If Complete, any remaining amount of the original authorized transaction is
automatically voided and all remaining open authorizations are voided.
Name-Value Pair API Developer Guide August 2012 27
Authorization and Capture API Operation Reference
3
DoCapture API Operation
Field Description
INVNUM (Optional) Your invoice number or other identification number that is displayed to
you and to the buyer in their transaction history. The value is recorded only if the
authorization you are capturing is an Express Checkout order authorization.
NOTE: This value on DoCapture overwrites a value previously set on
DoAuthorization.
Character length and limitations: 127 single-byte alphanumeric characters
NOTE (Optional) An informational note about this settlement that is displayed to the buyer
in email and in their transaction history.
Character length and limitations: 255 single-byte characters
SOFTDESCRIPTOR (Optional) Per transaction description of the payment that is passed to the buyer’s
credit card statement.
If you provide a value in this field, the full descriptor displayed on the buyer’s
statement has the following format:
<PP * | PAYPAL *><Merchant descriptor as set in the Payment
Receiving Preferences><1 space><soft descriptor>
Character length and limitations: The soft descriptor can contain only the following
characters:
Alphanumeric characters
- (dash)
* (asterisk)
. (period)
{space}
If you pass any other characters (such as “,”), PayPal returns an error code.
The soft descriptor does not include the phone number, which can be toggled between
your customer service number and PayPal’s Customer Service number.
The maximum length of the soft descriptor is 22 characters. Of this, the PayPal prefix
uses either 4 or 8 characters of the data format. Thus, the maximum length of the soft
descriptor information that you can pass in this field is:
22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment
Receiving Preferences> + 1)
For example, assume the following conditions:
The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.
The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
The soft descriptor is passed in as JanesFlowerGifts LLC.
The resulting descriptor string on the credit card is:
PAYPAL *EBAY JanesFlow
MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
28 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
NOTE: If you use version 56.0 or later of the DoCaptue API, only the authorization ID,
transaction ID, transaction type, payment date, gross amount, and payment status are
guaranteed to be returned. If you need the values of other fields and they are not
returned, you can obtain their values later by calling GetTransactionDetails or
by using the reporting mechanism. Not applicable to point of sale transactions.
3
DoCapture Response Fields
Field Description
AUTHORIZATIONID Authorization identification number you specified in the request.
Character length and limits: 19 single-byte characters maximum
MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
Payment Information Fields
Field Description
TRANSACTIONID Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters
Name-Value Pair API Developer Guide August 2012 29
Authorization and Capture API Operation Reference
3
DoCapture API Operation
Field Description
PARENTTRANSACTIONID Parent or related transaction identification number. This field is populated for the
following transaction types:
Reversal. Capture of an authorized transaction.
Reversal. Reauthorization of a transaction.
Capture of an order. The value of ParentTransactionID is the original
OrderID.
Authorization of an order. The value of ParentTransactionID is the original
OrderID.
Capture of an order authorization.
Void of an order. The value of ParentTransactionID is the original OrderID.
Character length and limitations: 16 digits
Only authorization of an order and capture of an order authorization apply to point-
of-sale transactions.
RECEIPTID Receipt identification number.
Character length and limitations: 16 digits
Empty for point-of-sale transactions.
TRANSACTIONTYPE The type of transaction. It is one of the following values:
cart
express-checkout
Character length and limitations:15 single-byte characters
PAYMENTTYPE Indicates whether the payment is instant or delayed. It is one of the following values:
none
echeck
instant
Character length and limitations: 7 single-byte characters
ORDERTIME Time/date stamp of payment. For example: 2006-08-15T17:23:15Z
AMT The final amount charged, including any shipping and taxes from your Merchant
Profile. Shipping and taxes do not apply to point-of-sale transactions.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,). Equivalent to 9 characters maximum for USD.
FEEAMT PayPal fee amount charged for the transaction.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,). Equivalent to 9 characters maximum for USD.
30 August 2012 Name-Value Pair API Developer Guide
Loading...