PayPal Name-Value Pair API 2012 User guide

Name-Value Pair API

Developer Guide

Last updated: August 2012

Name-Value Pair API Developer Guide

Document Number: 100018.en_US-201208

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.

2449, Luxembourg, R.C.S. Luxembourg B 118 349

Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval

of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.

Notice of non-liability:

PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,

implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused

by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use

of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.

Name-Value Pair API Developer Guide August 2012 3

Contents

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Contents

4 August 2012 Name-Value Pair API Developer Guide

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

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

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

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

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

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

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

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

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

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

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

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

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

DoVoid Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

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

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

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

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

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

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

Payment Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Name-Value Pair API Developer Guide August 2012 5

Contents

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

GetTransactionDetails Response Fields. . . . . . . . . . . . . . . . . . . . . . . . .121

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

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

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

Contents

6 August 2012 Name-Value Pair API Developer Guide

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

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

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

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

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

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

Chapter 10 ManagePendingTransactionStatus API Operation . . . . . 133

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

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

ManagePendingTransactionStatus Response Message . . . . . . . . . . . . . . . . . .134

ManagePendingTransactionStatus Response Fields . . . . . . . . . . . . . . . . . .134

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

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

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

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

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

Chapter 12 Recurring Payments and Reference Transactions API

Operations137

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

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

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

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

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

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

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

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

ManageRecurringPaymentsProfileStatus Response Message . . . . . . . . . . . . .154

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

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

BillOutstandingAmount Response Message. . . . . . . . . . . . . . . . . . . . . . .155

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

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

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

CreateBillingAgreement API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . .161

CreateBillingAgreement Request Message . . . . . . . . . . . . . . . . . . . . . . .161

Name-Value Pair API Developer Guide August 2012 7

Contents

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

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

SetCustomerBillingAgreement Request Message. . . . . . . . . . . . . . . . . . . .162

SetCustomerBillingAgreement Response Message . . . . . . . . . . . . . . . . . . .165

GetBillingAgreementCustomerDetails API Operation . . . . . . . . . . . . . . . . . . . .166

GetBillingAgreementCustomerDetails Request Message . . . . . . . . . . . . . . . .166

GetBillingAgreementCustomerDetails Response Message . . . . . . . . . . . . . . .166

BAUpdate API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168

BAUpdate Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168

BAUpdate Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168

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

DoReferenceTransaction Request Message . . . . . . . . . . . . . . . . . . . . . .171

DoReferenceTransaction Response Message . . . . . . . . . . . . . . . . . . . . .178

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

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

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

Merchant Store Details Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186

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

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

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

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

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

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

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

TransactionSearch Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . .192

TransactionSearch Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .192

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

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

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

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

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

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

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

Authorization and Capture API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .233

Contents

8 August 2012 Name-Value Pair API Developer Guide

GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237

TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237

RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239

MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242

Recurring Payments Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244

SetCustomerBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .251

GetBillingAgreementCustomerDetails Errors . . . . . . . . . . . . . . . . . . . . . . . .253

CreateBillingAgreement Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253

UpdateBillingAgreement Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254

DoReferenceTransaction Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255

AddressVerify API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262

ManagePendingTransactionStatus API Errors . . . . . . . . . . . . . . . . . . . . . . . .262

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

Appendix C State and Province Codes . . . . . . . . . . . . . . . . . 271

Appendix D Currency Codes . . . . . . . . . . . . . . . . . . . . . . 275

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

AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277

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

AVS Response Codes for Maestro . . . . . . . . . . . . . . . . . . . . . . . . . . .278

CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279

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

CVV2 Response Codes for Maestro. . . . . . . . . . . . . . . . . . . . . . . . . . .279

About Previous Versions of the API . . . . . . . . . . . . . . . . . . . 281

What’s New in Version 92.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281

What’s New in Version 89.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281

What’s New in Version 88.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281

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

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

New Field in RefundTransaction Response . . . . . . . . . . . . . . . . . . . . . . .282

New RefundInfoType in RefundTransaction Response . . . . . . . . . . . . . . . . .282

New Field in DoReferenceTransactionResponseDetailsType . . . . . . . . . . . . .282

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

Name-Value Pair API Developer Guide August 2012 9

Contents

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

New Field in DoCapture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . .283

New MerchantStoreDetailsType in DoCapture Request . . . . . . . . . . . . . . . . .283

New Fields in RefundTransaction Request . . . . . . . . . . . . . . . . . . . . . . .283

New MerchantStoreDetailsType in RefundTransaction Request . . . . . . . . . . . .284

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

New Fields in PaymentDetailsType in DoReferenceTransaction Request . . . . . . .285

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

New Behavior of DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . .285

New DoExpressCheckoutPayment Error Code . . . . . . . . . . . . . . . . . . . . .285

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

New TaxIdDetailsType Structure in SetExpressCheckout Request . . . . . . . . . . .286

New TaxIdDetailsType Structure in GetExpressCheckoutDetails Response . . . . . .286

What’s New in Version 69 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287

New PaymentDetailsItemType Structure in CreateRecurringPaymentsProfile Request . .

287

Changes to PaymentDetailsItemType in DoReferenceTransaction Request . . . . . .288

What’s New in Version 66 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289

Changes to PaymentDetailsType in SetExpressCheckout and

DoExpressCheckoutPayment Requests. . . . . . . . . . . . . . . . . . . . . . . . .289

Changes to PaymentDetailsItemTypein SetExpressCheckout and

DoExpressCheckoutPayment Requests . . . . . . . . . . . . . . . . . . . . . . . .289

Changes to PaymentDetailsItemType in GetExpressCheckoutDetails Response . . .291

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Contents

10 August 2012 Name-Value Pair API Developer Guide

Name-Value Pair API Developer Guide August 2012 11

What’s New

What’s New in Version 93.0

Maintenance release. New 10486 error code added for redirects when the process declines the

transaction: The transaction couldn’t be completed. Please redirect your customer to PayPal.

What’s New in Version 93.0

12 August 2012 Name-Value Pair API Developer Guide

Name-Value Pair API Developer Guide August 2012 13

Preface

About This Guide

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

Intended Audience

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

Pair API.

Where to Go for More Information

 Express Checkout Integration Guide

 Express Checkout Advanced Features Guide

 Merchant Setup and Administration Guide

Documentation Feedback

Help us improve this guide by sending feedback to:

documentationfeedback@paypal.com

Documentation Feedback

14 August 2012 Name-Value Pair API Developer Guide

Name-Value Pair API Developer Guide August 2012 15

1

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

Gateway Developer Guide and Reference.

PayPal API Client-Server Architecture

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

server.

A page on your website initiates an action on a PayPal API server by sending a request to the

server. The PayPal server responds with a confirmation that the requested action was taken or

indicates that an error occurred. The response might also contain additional information

related to the request. The following diagram shows the basic request-response mechanism.

For example, you might want to obtain the buyer’s shipping address from PayPal. You can

initiate a request specifying an API operation to obtain buyer details. The response from the

PayPal API server contains information about whether the request was successful. If the

operation succeeds, the response contains the requested information. In this case, the response

contains the buyer’s shipping address. If the operation fails, the response contains one or more

error messages.

Related information:

Creating an NVP Request

Responding to an NVP Response

PayPal Name-Value Pair API Basics

PayPal API Client-Server Architecture

1

16 August 2012 Name-Value Pair API Developer Guide

PayPal Name-Value Pair API Requests and Responses

To perform a PayPal NVP API operation, you send an NVP-formatted request to a PayPal

NVP server and interpret the response.

In the following diagram, your website generates a request. The request is executed on a

PayPal server and the response is returned to your site.

The request identifies:

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

version

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

 Credentials that identify the PayPal account making the request

 Request-specific information that controls the API operation to be performed

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

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

and whether any warning messages were returned

 Information that can be used by PayPal to track execution of the API operation

 Response-specific information required to fulfill the request

UTF-8 Character Encoding

The PayPal API assumes that all data in requests is in Unicode, specifically, the Unicode (or

UCS) Transformation Format, 8-bit encoding form (UTF-8).

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

Multiple API Operations

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

Typically, these features require you to:

Name-Value Pair API Developer Guide August 2012 17

PayPal Name-Value Pair API Basics

NVP Format

1

1. Invoke an API operation, such as SetExpressCheckout, that sets up the return URL to

which PayPal redirects your buyer’s browser after the buyer finishes on PayPal. Other

setup actions also can be performed by this API operation.

2. Invoke additional API operations after receiving the 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

PayPal Name-Value Pair API Basics

Creating an NVP Request

1

18 August 2012 Name-Value Pair API Developer Guide

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

FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore

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

Creating an NVP Request

The Name-Value Pair request format specifies the API operation to perform, credentials that

authorize PayPal to access your account, and fields containing additional information to be

used in the request.

Related information:

PayPal API Client-Server Architecture

Specifying the PayPal API Operation

For the NVP version of the PayPal API, you must specify the name of the PayPal API

operation to execute in each request along with the version of the API operation.

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

A method specifies the PayPal operation you want to execute, and each method is associated

with a version. Together, the method and version define the exact behavior of the API

operation. Typically, the behavior of an API operation does not change between versions;

however, you should carefully retest your code whenever you change a version.

To specify a method and version number:

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

METHOD=

operation

2. Choose the appropriate version.

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

VERSION=

version_number

Name-Value Pair API Developer Guide August 2012 19

PayPal Name-Value Pair API Basics

Creating an NVP Request

1

Specifying an API Credential Using Signatures

You must specify API credentials in each request to execute a PayPal API operation. You can

use either a signature or a certificate, but not both.

When you execute a PayPal API operation, you use credentials, such as a signature, to

authenticate that you are requesting the API operation. The following diagram shows the API

credentials part of an NVP request:

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

implementation. Consider storing these values in a secure location other than

your web server document root and setting the file permissions so that only

the system user that executes your ecommerce application can access it.

To enable PayPal to authenticate your request:

1. Specify the API username associated with your account.

USER=

API_username

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

PWD=

API_password

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

associated with the API username.

SIGNATURE=

API_signature

4. Optionally, you can specify the email address on file with PayPal of the third-party

merchant on whose behalf you are calling the API operation.

SUBJECT=

merchantEmailAddress

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

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

Specifying Credentials Using cURL

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

PayPal Name-Value Pair API Basics

Creating an NVP Request

1

20 August 2012 Name-Value Pair API Developer Guide

curl --insecure https://api-3t.sandbox.paypal.com/nvp -d ^

"METHOD=name^ &VERSION=XX.0^ &USER=API_username^ &PWD=API_password^

&SIGNATURE=API_signature^ &..."

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

paypal.com.

URL Encoding

All requests to execute PayPal API operations sent using HTTP must be URL-encoded. The

encoding ensures that you can transmit special characters, characters that are not allowed in a

URL, and characters that have special meaning in a URL, such as the equal sign and

ampersand.

The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a

PayPal API server. You must encode all data sent using the HTTP protocol because data that is

not encoded could be misinterpreted as part of the HTTP protocol instead of part of the

request. Most programming languages provide a way to encode strings in this way. You should

consistently URL-encode the complete API request; otherwise, you may find that

unanticipated data causes an error.

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

For example, consider the following NVP string:

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

It is encoded as follows:

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

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

Encoding and decoding methods for URLs

Language Method

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

Encoding.Default)

Decode System.Web.HttpUtility.UrlDecode(buffer,

Encoding.Default)

Classic ASP Encode Server.URLEncode

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

Internet.

Java Encode java.net.URLEncoder.encode

Decode java.net.URLDecoder.decode

Page is loading ...

PayPal Name-Value Pair API 2012 User guide

This manual is also suitable for

PayPal Name-Value Pair API 2012 User guide

Related papers

Other documents