PayPal Name-Value Pair API - 2013 Developer's Guide

Name-Value Pair API Developer Guide

Last updated: February 01, 2013

Name-Value Pair API Developer Guide

Document Number: 100018.en_US-201302

© 2013 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L2449, Luxembourg, R.C.S. Luxembourg B 118 349 Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

Notice of non-liability: PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.ear

What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

What's New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 1 PayPal Name-Value Pair API Basics . . . . . . . . . . . . .15

PayPal API Client-Server Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

PayPal Name-Value Pair API Requests and Responses . . . . . . . . . . . . . . . . 16

UTF-8 Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Multiple API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

NVP Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Creating an NVP Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Specifying the PayPal API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Specifying an API Credential Using Signatures . . . . . . . . . . . . . . . . . . . . . 19

URL Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

List Syntax for Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Executing NVP API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Specifying a PayPal Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Logging API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Responding to an NVP Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Common Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

URL Decoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 2 AddressVerify API Operation . . . . . . . . . . . . . . . .25

AddressVerify Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Address Verify Request Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

AddressVerify Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Name-Value Pair API Developer Guide February 01, 2013 3

Contents

Address Verify Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 3 Authorization and Capture API Operation Reference . . . .27

DoCapture API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

DoCapture Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

DoCapture Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

DoAuthorization API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

DoAuthorization Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

DoAuthorization Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . 33

DoReauthorization API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

DoReauthorization Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . 36

DoReauthorization Response Message . . . . . . . . . . . . . . . . . . . . . . . . . 37

DoVoid API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

DoVoid Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

DoVoid Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Chapter 4 DoDirectPayment API Operation . . . . . . . . . . . . . .41

DoDirectPayment Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

DoDirectPayment Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Credit Card Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Payer Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Payment Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Payment Details Item Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Ebay Item Payment Details Item Fields . . . . . . . . . . . . . . . . . . . . . . . . . 47

Ship To Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

3D Secure Request Fields (U.K. Merchants Only) . . . . . . . . . . . . . . . . . . . 48

DoDirectPayment Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

DoDirectPayment Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

ThreeDSecure Response Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Chapter 5 DoNonReferencedCredit API Operation . . . . . . . . . . .51

DoNonReferencedCredit Request Message . . . . . . . . . . . . . . . . . . . . . . . . . 51

DoNonReferencedCredit Request Fields . . . . . . . . . . . . . . . . . . . . . . . . 51

Credit Card Details Type Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Payer Name Type Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Payer Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

4 February 01, 2013 Name-Value Pair API Developer Guide

Contents

DoNonReferencedCredit Response Message . . . . . . . . . . . . . . . . . . . . . . . . 54

DoNonReferencedCredit Response Fields . . . . . . . . . . . . . . . . . . . . . . . 54

Chapter 6 ExpressCheckout API Operations . . . . . . . . . . . . . .55

Callback API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Callback API Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Callback Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

SetExpressCheckout API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

SetExpressCheckout Request Message . . . . . . . . . . . . . . . . . . . . . . . . 59

SetExpressCheckout Response Message. . . . . . . . . . . . . . . . . . . . . . . . 78

GetExpressCheckoutDetails API Operation . . . . . . . . . . . . . . . . . . . . . . . . . 78

GetExpressCheckoutDetails Request Message. . . . . . . . . . . . . . . . . . . . . 78

GetExpressCheckoutDetails Response Message . . . . . . . . . . . . . . . . . . . . 79

DoExpressCheckoutPayment API Operation . . . . . . . . . . . . . . . . . . . . . . . . 92

DoExpressCheckoutPayment Request Message . . . . . . . . . . . . . . . . . . . . 92

DoExpressCheckoutPayment Response Message . . . . . . . . . . . . . . . . . . .105

Chapter 7 GetBalance API Operation. . . . . . . . . . . . . . . . . 117

GetBalance Request Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

GetBalance Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

GetBalance Response Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

GetBalance Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117

Chapter 8 GetPalDetails API Operation . . . . . . . . . . . . . . . 119

GetPalDetails Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

GetPalDetails Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

GetPalDetails Response Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119

GetPalDetails Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Chapter 9 GetTransactionDetails API Operation . . . . . . . . . . . 121

GetTransactionDetails Request Message . . . . . . . . . . . . . . . . . . . . . . . . . .121

GetTransactionDetails Request Fields. . . . . . . . . . . . . . . . . . . . . . . . . .121

GetTransactionDetails Response Message . . . . . . . . . . . . . . . . . . . . . . . . .121

GetTransactionDetails Response Fields. . . . . . . . . . . . . . . . . . . . . . . . .122

Receiver Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123

Payer Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123

Payer Name Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

Name-Value Pair API Developer Guide February 01, 2013 5

Contents

Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

Payment Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125

Payment Item Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . .129

Payment Item Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

Auction Information Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131

Subscription Terms Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131

Chapter 10 ManagePendingTransactionStatus API Operation . . . . . 133

ManagePendingTransactionStatus Request Message. . . . . . . . . . . . . . . . . . . .133

ManagePendingTransactionStatus Request Fields . . . . . . . . . . . . . . . . . . .133

ManagePendingTransactionStatus Response Message . . . . . . . . . . . . . . . . . . .133

ManagePendingTransactionStatus Response Fields . . . . . . . . . . . . . . . . . .133

Chapter 11 MassPay API Operation . . . . . . . . . . . . . . . . . . 135

MassPay Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

MassPay Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

MassPay Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

MassPay Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135

Chapter 12 Recurring Payments and Reference Transactions API Ops 137

CreateRecurringPaymentsProfile API Operation . . . . . . . . . . . . . . . . . . . . . .137

CreateRecurringPaymentsProfile Request Message . . . . . . . . . . . . . . . . . .137

CreateRecurringPaymentsProfile Response Message . . . . . . . . . . . . . . . . .145

GetRecurringPaymentsProfileDetails API Operation . . . . . . . . . . . . . . . . . . . .146

GetRecurringPaymentsProfileDetails Request Message . . . . . . . . . . . . . . . .146

GetRecurringPaymentsProfileDetails Response Message . . . . . . . . . . . . . . .146

ManageRecurringPaymentsProfileStatus API Operation . . . . . . . . . . . . . . . . . .154

ManageRecurringPaymentsProfileStatus Request Message . . . . . . . . . . . . . .154

ManageRecurringPaymentsProfileStatus Response Message . . . . . . . . . . . . .155

BillOutstandingAmount API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . .155

BillOutstandingAmount Request Message . . . . . . . . . . . . . . . . . . . . . . .155

BillOutstandingAmount Response Message. . . . . . . . . . . . . . . . . . . . . . .156

UpdateRecurringPaymentsProfile API Operation . . . . . . . . . . . . . . . . . . . . . .156

UpdateRecurringPaymentsProfile Request Message . . . . . . . . . . . . . . . . . .156

UpdateRecurringPaymentsProfile Response Message . . . . . . . . . . . . . . . . .161

CreateBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . .162

CreateBillingAgreement Request Message . . . . . . . . . . . . . . . . . . . . . . .162

CreateBillingAgreement API Response Message . . . . . . . . . . . . . . . . . . . .162

6 February 01, 2013 Name-Value Pair API Developer Guide

Contents

SetCustomerBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . .162

SetCustomerBillingAgreement Request Message. . . . . . . . . . . . . . . . . . . .163

SetCustomerBillingAgreement Response Message . . . . . . . . . . . . . . . . . . .166

GetBillingAgreementCustomerDetails API Operation . . . . . . . . . . . . . . . . . . . .167

GetBillingAgreementCustomerDetails Request Message . . . . . . . . . . . . . . . .167

GetBillingAgreementCustomerDetails Response Message . . . . . . . . . . . . . . .167

BAUpdate API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169

BAUpdate Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169

BAUpdate Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169

DoReferenceTransaction API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . .171

DoReferenceTransaction Request Message . . . . . . . . . . . . . . . . . . . . . .172

DoReferenceTransaction Response Message . . . . . . . . . . . . . . . . . . . . .179

Chapter 13 RefundTransaction API Operation . . . . . . . . . . . . . 185

RefundTransaction Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .185

RefundTransaction Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .185

Merchant Store Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187

RefundTransaction Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . .187

RefundTransaction Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .187

RefundInfoType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188

Chapter 14 TransactionSearch API Operation . . . . . . . . . . . . . 189

TransactionSearch Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .189

TransactionSearch Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .189

Payer Name Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191

TransactionSearch Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . .191

TransactionSearch Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .191

Appendix A API Error Codes . . . . . . . . . . . . . . . . . . . . . . 193

General API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193

Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194

DirectPayment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197

SetExpressCheckout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209

GetExpressCheckoutDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . .223

DoExpressCheckoutPayment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . .224

Authorization and Capture API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .234

GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238

Name-Value Pair API Developer Guide February 01, 2013 7

Contents

TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239

RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240

MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244

Recurring Payments Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247

SetCustomerBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .254

GetBillingAgreementCustomerDetails Errors . . . . . . . . . . . . . . . . . . . . . . . .256

CreateBillingAgreement Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .257

UpdateBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .257

DoReferenceTransaction Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258

AddressVerify API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268

ManagePendingTransactionStatus API Errors . . . . . . . . . . . . . . . . . . . . . . . .268

Appendix B Countries and Regions Supported by PayPal . . . . . . 271

Appendix C State and Province Codes . . . . . . . . . . . . . . . . . 279

Appendix D Currency Codes . . . . . . . . . . . . . . . . . . . . . . 283

Appendix E AVS and CVV2 Response Codes . . . . . . . . . . . . . 287

AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287

AVS Response Codes for Visa, MasterCard, Discover, and American Express . . . .287

AVS Response Codes for Maestro . . . . . . . . . . . . . . . . . . . . . . . . . . .288

CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289

CVV2 Response Codes for Visa, MasterCard, Discover, and American Express . . . .289

CVV2 Response Codes for Maestro. . . . . . . . . . . . . . . . . . . . . . . . . . .289

Appendix About Previous Versions of the API . . . . . . . . . . . . 291

What's New in Version 95.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

What's New in Version 93.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

What's New in Version 92.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

What's New in Version 91.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

What's New in Version 89.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

What's New in Version 88.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292

What’s New in Version 85.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292

What’s New in Version 84.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292

New Field in RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . .292

8 February 01, 2013 Name-Value Pair API Developer Guide

Contents

New RefundInfoType in RefundTransaction Response . . . . . . . . . . . . . . . . .292

New Field in DoReferenceTransactionResponseDetailsType . . . . . . . . . . . . .293

New Field in DoDirectPaymentResponse . . . . . . . . . . . . . . . . . . . . . . . .293

What’s New in Version 82.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293

New Field in DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . .293

New MerchantStoreDetailsType in DoCapture Request. . . . . . . . . . . . . . . . .293

New Fields in RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . .294

New MerchantStoreDetailsType in RefundTransaction Request . . . . . . . . . . . .294

What’s New in Version 80.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295

New Fields in PaymentDetailsType in DoReferenceTransaction Request . . . . . . .295

What’s New in Version 74.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295

New Behavior of DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . .295

New DoExpressCheckoutPayment Error Code . . . . . . . . . . . . . . . . . . . . .296

What’s New in Version 72.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296

New TaxIdDetailsType Structure in SetExpressCheckout Request . . . . . . . . . . .296

New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response . . . . . .296

What's New in Version 69 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297

New PaymentDetailsItemType Structure in CreateRecurringPaymentsProfile Request 297

Changes to PaymentDetailsItemType in DoReferenceTransaction Request . . . . . .298

What's New in Version 66 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299

Changes to PaymentDetailsType in SetExpressCheckout and

DoExpressCheckoutPayment Requests. . . . . . . . . . . . . . . . . . . . . . . . .299

Changes to PaymentDetailsItemTypein SetExpressCheckout and

DoExpressCheckoutPayment Requests . . . . . . . . . . . . . . . . . . . . . . . .299

Changes to PaymentDetailsItemType in GetExpressCheckoutDetails Response . . .301

Appendix Revision History . . . . . . . . . . . . . . . . . . . . . . 303

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Name-Value Pair API Developer Guide February 01, 2013 9

Contents

10 February 01, 2013 Name-Value Pair API Developer Guide

What's New

Maintenance release. See the latest version of the PayPal Merchant API Release Notes for more information:

notes#MerchantAPI

What’s New

https://www.x.com/developers/paypal/documentation-tools/release-

Name-Value Pair API Developer Guide February 01, 2013 11

What's New

12 February 01, 2013 Name-Value Pair API Developer Guide

Preface

About This Guide

The Name-Value Pair API Developer Guide describes the PayPal Name-Value Pair API.

Intended Audience

This guide is written for developers who are implementing solutions using the Name-Value Pair API.

Where to Go for More Information

 Express Checkout Integration Guide

 Express Checkout Advanced Features Guide

 Merchant Setup and Administration Guide

Documentation Feedback

Help us improve this guide by sending feedback to: documentationfeedback@paypal.com

Name-Value Pair API Developer Guide February 01, 2013 13

Documentation Feedback

14 February 01, 2013 Name-Value Pair API Developer Guide

PayPal Name-Value Pair API

Basics

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

NOTE: The PayFlow API also uses name-value pairs to provide parameter-based association

between request and response fields of a message and their values; however, the PayFlow API is not the same as the NVP API; for more information about the PayFlow API, see

PayPal API Client-Server Architecture

The PayPal API uses a client-server model in which your website is a client of the PayPal server.

Gateway Developer Guide and Reference.

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

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

Related information:

Creating an NVP Request

Responding to an NVP Response

Name-Value Pair API Developer Guide February 01, 2013 15

PayPal Name-Value Pair API Basics

PayPal API Client-Server Architecture

PayPal Name-Value Pair API Requests and Responses

To perform a PayPal NVP API operation, you send an NVP-formatted request to a PayPal NVP server and interpret the response.

In the following diagram, your website generates a request. The request is executed on a PayPal server and the response is returned to your site.

The request identifies:

 The name of the API operation, specified by METHOD=name, to be performed and its

version

NOTE: After the METHOD parameter, you can specify the parameters in any order.

 Credentials that identify the PayPal account making the request  Request-specific information that controls the API operation to be performed

A PayPal API server performs the operation and returns a response. The response contains:

 An acknowledgement status that indicates whether the operation was a success or failure

and whether any warning messages were returned

 Information that can be used by PayPal to track execution of the API operation  Response-specific information required to fulfill the request

UTF-8 Character Encoding

The PayPal API assumes that all data in requests is in Unicode, specifically, the Unicode (or UCS) Transformation Format, 8-bit encoding form (UTF-8).

In responses, the API always returns data in UTF-8.

Multiple API Operations

Some of the features, such as Express Checkout, require you to call multiple API operations. Typically, these features require you to:

16 February 01, 2013 Name-Value Pair API Developer Guide

PayPal Name-Value Pair API Basics

NVP Format

1. Invoke an API operation, such as SetExpressCheckout, that sets up the return URL to which PayPal redirects your buyer’s browser after the buyer finishes on PayPal. Other setup actions also can be performed by this API operation.

2. Invoke additional API operations after receiving the buyer’s permission on PayPal, for example, GetExpressCheckoutDetails or DoExpressCheckoutPayment.

The following diagram shows the execution flow between your site and PayPal:

Token Usage

Typically, the API operation that sets up a redirection to PayPal returns a token. This token is passed as a parameter in the redirect to PayPal. The token also might be required in related API operations.

NVP Format

NVP is a way of specifying names and values in a string. NVP is the informal name for the query in the URI specification. The NVP string is appended to the URL.

An NVP string conforms to the following guidelines:

 The name is separated from the value by an equal sign (=). For example:

FIRSTNAME=Robert

Name-Value Pair API Developer Guide February 01, 2013 17

PayPal Name-Value Pair API Basics

Creating an NVP Request

 Name-value pairs are separated by an ampersand (&). For example:

FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore

 The values for each value in an NVP string are URL-encoded.

Related information:

Name-Value Pair Syntax Supporting Parallel Payments

Creating an NVP Request

The Name-Value Pair request format specifies the API operation to perform, credentials that authorize PayPal to access your account, and fields containing additional information to be used in the request.

Related information:

PayPal API Client-Server Architecture

Specifying the PayPal API Operation

For the NVP version of the PayPal API, you must specify the name of the PayPal API operation to execute in each request along with the version of the API operation.

The following diagram shows the API operation part of an NVP request:

A method specifies the PayPal operation you want to execute, and each method is associated with a version. Together, the method and version define the exact behavior of the API operation. Typically, the behavior of an API operation does not change between versions; however, you should carefully retest your code whenever you change a version.

To specify a method and version number:

1. Choose the PayPal API operation you want to use.

METHOD=

18 February 01, 2013 Name-Value Pair API Developer Guide

operation

PayPal Name-Value Pair API Basics

2. Choose the appropriate version.

In most cases, you should use the latest version of the API operation.

Creating an NVP Request

VERSION=

version_number

Specifying an API Credential Using Signatures

You must specify API credentials in each request to execute a PayPal API operation. You can use either a signature or a certificate, but not both.

When you execute a PayPal API operation, you use credentials, such as a signature, to authenticate that you are requesting the API operation. The following diagram shows the API credentials part of an NVP request:

IMPORTANT: You must protect the values for USER, PWD, and SIGNATURE in your

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

To enable PayPal to authenticate your request:

1. Specify the API username associated with your account.

USER=

API_username

2. Specify the password associated with the API user name.

API_password

PWD=

3. If you are using an API signature and not an API certificate, specify the API signature associated with the API username.

SIGNATURE=

API_signature

4. Optionally, you can specify the email address on file with PayPal of the third-party merchant on whose behalf you are calling the API operation.

Name-Value Pair API Developer Guide February 01, 2013 19

PayPal Name-Value Pair API Basics

Creating an NVP Request

SUBJECT=merchantEmailAddress

NOTE: Typically, a merchant grants third-party permissions to a shopping cart. The merchant

previously must have given you permission to execute the API operation.

Specifying Credentials Using cURL

The following example shows one way to specify a signature using cURL:

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

NOTE: This example does not establish a secure connection and should not be used live on

paypal.com.

URL Encoding

All requests to execute PayPal API operations sent using HTTP must be URL-encoded. The encoding ensures that you can transmit special characters, characters that are not allowed in a URL, and characters that have special meaning in a URL, such as the equal sign and ampersand.

The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a PayPal API server. You must encode all data sent using the HTTP protocol because data that is not encoded could be misinterpreted as part of the HTTP protocol instead of part of the request. Most programming languages provide a way to encode strings in this way. You should consistently URL-encode the complete API request; otherwise, you may find that unanticipated data causes an error.

NOTE: An HTTP form is automatically URL-encoded by most browsers.

For example, consider the following NVP string:

NAME=Robert Moore&COMPANY=R. H. Moore & Associates

It is encoded as follows:

NAME=Robert+Moore&COMPANY=R.+H.+Moore+%26+Associates

Use the following methods to URL-encode or URL-decode your NVP strings:

Encoding and decoding methods for URLs

Language Method

ASP.NET Encode System.Web.HttpUtility.UrlEncode(buffer,

Encoding.Default)

Decode System.Web.HttpUtility.UrlDecode(buffer,

Encoding.Default)

20 February 01, 2013 Name-Value Pair API Developer Guide

PayPal Name-Value Pair API Basics

Executing NVP API Operations

Language Method

Classic ASP Encode Server.URLEncode

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

Internet.

Java Encode java.net.URLEncoder.encode

Decode java.net.URLDecoder.decode

PHP Encode urlencode()

Decode urldecode()

ColdFusion Encode URLEncodedFormatstring [, charset]

Decode URLDecodeurlEncodedString[, charset])

Related information:

URL Decoding

List Syntax for Name-Value Pairs

The PayPal API uses a special syntax for NVP fields defined as lists. The NVP interface to the PayPal API requires a unique name for each field. In the API, lists

are prefixed by L_. To identify an element within the list, use the offset from the beginning of the list, starting with 0 as the first element. For example, L_DESC0 is the first line of a description, L_DESC1, is the second line, and so on.

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

element.

Executing NVP API Operations

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

Specifying a PayPal Server

You execute a PayPal API operation by submitting the request to a PayPal API server.

Name-Value Pair API Developer Guide February 01, 2013 21

PayPal Name-Value Pair API Basics

Responding to an NVP Response

To execute a PayPal NVP API operation, submit the request to one of the following end points:

Server end point Description

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

https://api-3t.paypal.com/nvp PayPal “live” production server for use with API signatures

https://api.sandbox.paypal.com/nvp Sandbox server for use with API certificates; use for testing

https://api.paypal.com/nvp PayPal “live” production server for use with API certificates

NOTE: You must use different API credentials for each server end point. Typically, you

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

your API

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

Logging API Operations

You should log basic information from the request and response messages of each PayPal API operation you execute. You must log the Correlation ID from the response message, which identifies the API operation to PayPal and must be provided to Merchant Technical Support if you need their assistance with a specific transaction.

All responses to PayPal API operations contain information that may be useful for debugging purposes. In addition to logging the Correlation ID from the response message, you can log other information, such as the transaction ID and timestamp, to enable you to review a transaction on the PayPal website or through the API. You could implement a scheme that logs the entire request and response in a “verbose” mode; however, you should never log the password from a request.

Responding to an NVP Response

The Name-Value Pair response consists of the answer to the request as well as common fields that identify the API operation and how it was executed.

The following diagram shows fields in the response to a PayPal NVP API operation:

22 February 01, 2013 Name-Value Pair API Developer Guide

Related information:

PayPal API Client-Server Architecture

Common Response Fields

The PayPal API always returns common fields in addition to fields that are specific to the requested PayPal API operation.

A PayPal API response includes the following fields:

PayPal Name-Value Pair API Basics

Responding to an NVP Response

Field Description

ACK Acknowledgement status, which is one of the following values:

 Success indicates a successful operation.  SuccessWithWarning indicates a successful operation; however, there are

messages returned in the response that you should examine.

 Failure indicates the operation failed; the response also contains one or more error

messages explaining the failure.

 FailureWithWarning indicates that the operation failed and that there are

messages returned in the response that you should examine.

CORRELATIONID Correlation ID, which uniquely identifies the transaction to PayPal.

TIMESTAMP The date and time that the requested API operation was performed.

VERSION The version of the API.

BUILD The sub-version of the API.

Error Responses

If the ACK value is not Success, API response fields may not be returned. An error response has the following general format.

Name-Value Pair API Developer Guide February 01, 2013 23

PayPal Name-Value Pair API Basics

Responding to an NVP Response

Format of an Error Response

Response Fields on Error

Additional pass-through information may appear in the L_ERRORPARAMIDn and

L_ERRORPARAMVALUE

TIMESTAMP=2011%2d11%2d15T20%3a27%3a02Z&CORRELATIONID=5be53331d9700&ACK=Fail ure&VERSION=78%2e0&BUILD=000000&L_ERRORCODE0=15005&L_SHORTMESSAGE0=Processo r%20Decline&L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e& L_SEVERITYCODE0=Error&L_ERRORP ARAMID0=ProcessorR esponse&L_ERRORPARAMV ALUE0= 0051&AMT=10%2e40&CURRENCYCODE=USD&AVSCODE=X&CVV2MATCH=M

In this case, the parameter ID is ProcessorResponse, which indicates an error response by a credit or debit card processor. The value contains the processor-specific error. These values are not set by PayPal; rather, they are passed through from the source.

NOTE: PayPal only passes selected values in the L_ERRORPARAMIDn and

ACK=notSuccess&TIMESTAMP=date/timeOfResponse& CORRELATIONID= BUILD= L_SHORTMESSAGE0= L_LONGMESSAGE0= L_SEVERITYCODE0=

buildNumber&L_ERRORCODE0=errorCode&

L_ERRORPARAMVALUE

debuggingToken&VERSION=VersionNo&

shortMessage&

longMessage&

severityCode

n fields. Consider the following error response:

n fields.

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

URL Decoding

All responses to HTTP POST operations used by the PayPal NVP API must be decoded.

The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a PayPal API server. You must decode all data returned using the HTTP protocol so that it can be displayed properly. Most programming languages provide a way to decode strings.

Related information:

URL Encoding

24 February 01, 2013 Name-Value Pair API Developer Guide

AddressVerify API Operation

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

AddressVerify Request Message

Address Verify Request Fields

Field Description

METHOD (Required) Must be AddressVerify.

EMAIL (Required) Email address of a PayPal member to verify.

Character length and limitations: 255 single-byte characters maximum with the input mask: ?@?.??

STREET (Required) First line of the billing or shipping postal address to verify. To pass

verification, the value of Street must match the first 3 single-byte characters of a postal address on file for the PayPal member.

Character length and limitations: 35 single-byte characters maximum, including alphanumeric plus - , . ‘ # \. Whitespace and case of input value are ignored.

ZIP (Required) Postal code to verify. To pass verification, the value of Zip must match

the first 5 single-byte characters of the postal code of the verified postal address for the verified PayPal member.

Character length and limitations: 16 single-byte characters maximum. Whitespace and case of input value are ignored.

Name-Value Pair API Developer Guide February 01, 2013 25

AddressVerify API Operation

AddressVerify Response Message

Address Verify Response Fields

Field Description

CONFIRMATIONCODE Indicates whether the address is a confirmed address on file at PayPal. It is one of the

following values:

 None – The request value of the Email element does not match any email address

on file at PayPal.

 Confirmed – If the response value of the StreetMatch element is Matched,

the entire postal address is confirmed.

 Unconfirmed – PayPal responds that the postal address is unconfirmed.

NOTE: The values Confirmed and Unconfirmed both indicate that the member

email address passed verification.

STREETMATCH Indicates whether the street address matches address information on file at PayPal. It

is one of the following values:

 None – The request value of the Email element does not match any email address

on file at PayPal. No comparison of other request values was made.

 Matched – The request value of the Street element matches the first 3 single-byte

characters of a postal address on file for the PayPal member.

 Unmatched – The request value of the Street element does not match any

postal address on file for the PayPal member.

ZIPMATCH Indicates whether the zip address matches address information on file at PayPal. It is

one of the following values:

 None – The request value of the Street element was unmatched. No comparison

of the Zip element was made.

 Matched – The request value of the Zip element matches the zip code of the

postal address on file for the PayPal member.

 Unmatched – The request value of the Zip element does not match the zip code

of the postal address on file for the PayPal member.

COUNTRYCODE Country code (ISO 3166) on file for the PayPal email address.

Character length and limitations: 2 single-byte characters

TOKEN The token contains encrypted information about the member’s email address and

postal address. If you pass the value of the token in the HTML variable address_api_token of Buy Now buttons, PayPal prevents the buyer from using an email address or postal address other than those that PayPal verified with this API call. The token is valid for 24 hours.

Character length and limitations: 94 single-byte characters

26 February 01, 2013 Name-Value Pair API Developer Guide

Authorization and Capture API

Operation Reference

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

DoCapture API Operation

Captures an authorized payment.

DoCapture Request Message

DoCapture Request Fields

Field Description

METHOD (Required) Must be DoCapture.

AUTHORIZATIONID (Required) Authorization identification number of the payment you want to capture.

This is the transaction ID returned from DoExpressCheckoutPayment, DoDirectPayment, or CheckOut. For point-of-sale transactions, this is the transaction ID returned by the CheckOut call when the payment action is Authorization.

Character length and limitations: 19 single-byte characters maximum

AMT (Required) Amount to capture.

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

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

COMPLETETYPE (Required) Indicates whether or not this is your last capture. It is one of the following

values:

 Complete – This is the last capture you intend to make.  NotComplete – You intend to make additional captures.

NOTE: If Complete, any remaining amount of the original authorized transaction is

automatically voided and all remaining open authorizations are voided.

Name-Value Pair API Developer Guide February 01, 2013 27

Authorization and Capture API Operation Reference

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:

Character length and limitations: The soft descriptor can contain only the following characters:

 Alphanumeric characters  - (dash)  * (asterisk)  . (period)  {space}

If you pass any other characters (such as “,”), PayPal returns an error code. The soft descriptor does not include the phone number, which can be toggled between

your customer service number and PayPal’s Customer Service number. The maximum length of the soft descriptor is 22 characters. Of this, the PayPal prefix

uses either 4 or 8 characters of the data format. Thus, the maximum length of the soft descriptor information that you can pass in this field is:

22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment Receiving Preferences> + 1)

For example, assume the following conditions:

 The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.  The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.  The soft descriptor is passed in as JanesFlowerGifts LLC.

The resulting descriptor string on the credit card is:

PAYPAL *EBAY JanesFlow

MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This

ID can later be used to request the latest results for a previous request without generating a new request. Examples of this include requests due to timeouts or errors during the original request.

Character length and limitations: string of up to 38 single-byte characters. This field is available since version 92.0.

28 February 01, 2013 Name-Value Pair API Developer Guide

Authorization and Capture API Operation Reference

DoCapture API Operation

Merchant Store Details Fields

Field Description

STOREID Identifier of the merchant store at which the refund is given. This field is

required for point-of-sale transactions. Character length and limitations: 50 single-byte characters This field is available since version 82.0.

TERMINALID (Optional) ID of the terminal.

Character length and limitations: 50 single-byte characters This field is available since version 82.0.

DoCapture Response Message

NOTE: If you use version 56.0 or later of the DoCaptue API, only the authorization ID,

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

DoCapture Response Fields

Field Description

AUTHORIZATIONID Authorization identification number you specified in the request.

Character length and limits: 19 single-byte characters maximum

MSGSUBID (Optional) A message ID used for idempotence to uniquely identify a message. This

ID can later be used to request the latest results for a previous request without generating a new request. Examples of this include requests due to timeouts or errors during the original request.

Character length and limitations: string of up to 38 single-byte characters. This field is available since version 92.0.

Payment Information Fields

Field Description

TRANSACTIONID Unique transaction ID of the payment.

Character length and limitations: 17 single-byte characters

Name-Value Pair API Developer Guide February 01, 2013 29

Authorization and Capture API Operation Reference

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.

30 February 01, 2013 Name-Value Pair API Developer Guide

+ 288 hidden pages