Paypal Name Value Pair Api 2007 Reference Manual Developer Guide And

Name-Value Pair API - 2007 - Reference for Germany PP_NVP-API-Ref-Germany_2007 Free User Guide for PayPal Software, Manual

2015-07-27

: Paypal Paypal-Name-Value-Pair-Api-2007-Reference-Manual-777968 paypal-name-value-pair-api-2007-reference-manual-777968 paypal pdf

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

DownloadPaypal Paypal-Name-Value-Pair-Api-2007-Reference-Manual- Name-Value Pair API Developer Guide And Reference  Paypal-name-value-pair-api-2007-reference-manual
Open PDF In BrowserView PDF
Name-Value Pair API
Reference for
Germany

For Professional Use in Germany Only
Currently only available in English.
A usage Professional en Allemagne uniquement
Disponible en Anglais uniquement pour l’instant.

Last updated: April 2007

PayPal Name-Value Pair API Developer Guide and Reference
Document Number: 100018.en_DE-20070410

© 2007 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.
PayPal (Europe) Ltd. is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution.
PayPal FSA Register Number: 226056.
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

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Documentation Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Introducing the PayPal NVP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Integrating with the PayPal API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Basic Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Create a Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Get API Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Create and Post the Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Interpret the Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Taking Your Application Live . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Set Up a PayPal Business Account . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Set Up API Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Modify Your Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Request-Response Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Posting Using HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 2

Accepting PayPal in Express Checkout . . . . . . . . . . . 17

Basic Checkout with PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1. Starting the Checkout Using SetExpressCheckout . . . . . . . . . . . . . . . . . . 18
2. Redirecting the Customer’s Browser to PayPal Login Page . . . . . . . . . . . . . 18
3. Getting Payer Details Using GetExpressCheckoutDetails . . . . . . . . . . . . . . 19
4. Making a Sale Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . 19
Support giropay and electronic funds transfer . . . . . . . . . . . . . . . . . . . . . . . . 20
Initiate the Flow with SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . 20
Redirecting the Customer to PayPal. . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Name-Value Pair API Developer Guide and Reference

April 2007

3

Contents

Completing the Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Controlling the Shipping Address Using SetExpressCheckout . . . . . . . . . . . . . . . 21
Suppressing Display of Shipping Address on PayPal . . . . . . . . . . . . . . . . . . 21
Overriding the Shipping Address Stored on PayPal . . . . . . . . . . . . . . . . . . . 22
Changing the Language on the PayPal Login Page Using SetExpressCheckout . . . . . . 23
Changing the Logo on the PayPal Pages Using SetExpressCheckout . . . . . . . . . . . 23
Specifying a Custom Payment Page Style. . . . . . . . . . . . . . . . . . . . . . . . 23
Specifying Logo and Color Settings Individually . . . . . . . . . . . . . . . . . . . . . 24
Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails. . . . . . . . 24
Making a Sale Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . 25
Changing the URL for IPN Using DoExpressCheckoutPayment . . . . . . . . . . . . . . 25
Including Line Item Details Using DoExpressCheckoutPayment . . . . . . . . . . . . . . 26
Including Subtotals Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . 27
Updating Order Details Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . 27
Updating the Shipping Address Using DoExpressCheckoutPayment . . . . . . . . . . . . 28

Chapter 3

Back-Office Administration . . . . . . . . . . . . . . . . . 31

Refunding Using RefundTransaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Full Refund. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Partial Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Including a Note with the Refund . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Searching for Transactions Using TransactionSearch . . . . . . . . . . . . . . . . . . . . 32
Viewing Details of a Single Transaction Using GetTransactionDetails . . . . . . . . . . . 33

Appendix A NVP API Method and Field Reference . . . . . . . . . . . . 35
General Characteristics of Requests and Parameters . . . . . . . . . . . . . . . . . . . . 35
Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Multi-Value Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
PayPal-Supported Transactional Currencies . . . . . . . . . . . . . . . . . . . . . . 35
Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
SetExpressCheckout Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
SetExpressCheckout Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
GetExpressCheckoutDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . 41
GetExpressCheckoutDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . 42
DoExpressCheckoutPayment Request . . . . . . . . . . . . . . . . . . . . . . . . . 43
DoExpressCheckoutPayment Response . . . . . . . . . . . . . . . . . . . . . . . . 47

4

April 2007

Name-Value Pair API Developer Guide and Reference

Contents

RefundTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
TransactionSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
GetTransactionDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Mass Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Appendix B Error Message Reference . . . . . . . . . . . . . . . . . . 63
Error Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
General API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Express Checkout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
RefundTransaction API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
TransactionSearch API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
GetTransactionDetails API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
MassPay API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Appendix C NVP API Web Samples . . . . . . . . . . . . . . . . . . . . 95
Descriptions of the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Accepting PayPal in Express Checkout . . . . . . . . . . . . . . . . . . . . . . . . . 95
Getting Transaction Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Common Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Sample API User with API Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Samples Using PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Download and Unzip the Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Installing the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Samples Using Classic ASP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Download and Unzip the Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Installing the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Samples Using ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Download and Unzip the Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Installing the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Name-Value Pair API Developer Guide and Reference

April 2007

5

Contents

Appendix D The Java SDK . . . . . . . . . . . . . . . . . . . . . . . 103
Installing the Java SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Supported Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Recommended Hardware Configuration. . . . . . . . . . . . . . . . . . . . . . . . .104
Download and Unzip the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Post-installation Set-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Complete SDK and API Class Documentation. . . . . . . . . . . . . . . . . . . . . . . .105
SDK Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Overview to Profile-related Classes . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Sample API User with API Signature . . . . . . . . . . . . . . . . . . . . . . . . . .108
Sample API User with API Certificate . . . . . . . . . . . . . . . . . . . . . . . . . .108

Appendix E The ASP.NET SDK . . . . . . . . . . . . . . . . . . . . . 109
Installing the ASP.NET SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Supported Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Downloading and Installing the SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Post-installation Set-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Optional Custom Configurations in Web.config . . . . . . . . . . . . . . . . . . . . . 111
SDK Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Enabling Proxy Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Uninstalling the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Complete SDK and API Class Documentation. . . . . . . . . . . . . . . . . . . . . . . . 113
Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Overview to Profile-related Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Sample API User with API Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Sample API User with API Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Installing the Samples in IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Appendix F

Country Codes

. . . . . . . . . . . . . . . . . . . . . . 117

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

6

April 2007

Name-Value Pair API Developer Guide and Reference

Preface

This Document
The PayPal Name-Value Pair API Developer Guide and Reference describes the PayPal
Name-Value Pair API.

Intended Audience
The PayPal Name-Value Pair API Developer Guide and Reference is written for web
developers who are implementing solutions using the Name-Value Pair API.

Documentation Problems
If you discover any errors in or have any problems with this documentation, please email us by
following the instructions below. Describe the error or problem as completely as possible and
give us the document title, the date of the document, and the page number or page range.
To contact Developer Technical Support about documentation problems:
Log in to your account at https://developer.paypal.com/ by entering your email address and
password in the Member Log In box
Click Help Center at the bottom of the box on the right side of the page.
Click Email PayPal Technical Support.
Complete the form.

Name-Value Pair API Developer Guide and Reference

April 2007

7

Preface
Revision History

Revision History
Revision history for PayPal Name-Value Pair API Developer Guide and Reference.
TABLE P.1 Revision History
Date

Description

April 2007

Revised document to represent specifics for Germany.

February 2007

8

Bug fixes including updating Line Item Details for Express Checkout APIs, dding

SHIPTOCOUNTRYCODE, and adding Switch/Solo codes for AVS and CVV2.

December 2006

Updates for bug fixes.

October 2006

First public release.

April 2007

Name-Value Pair API Developer Guide and Reference

1

Overview

This chapter describes the PayPal Name-Value Pair (NVP) API at a high level and contains the
following sections:
z

Introducing the PayPal NVP API

z

Basic Steps

z

Taking Your Application Live

z

Technical Details

Introducing the PayPal NVP API
The PayPal NVP API is a simple programmatic interface that allows you, the merchant, to
access PayPal’s business functionality to:
z

Accept PayPal in checkout on your website using Express Checkout.

z

Pay one or more recipients using Mass Payment.

z

Issue full refunds or multiple partial refunds.

z

Search transactions using a start date or other criteria.

z

View details of a specific transaction.

The PayPal NVP API makes it easy to add PayPal to your web application. You construct an
NVP string and post it to the PayPal server using HTTPS. PayPal posts back a reponse in NVP
format.

Integrating with the PayPal API
You can develop with the PayPal NVP API using two different approaches:
Integrate Directly

You can integrate directly with the PayPal NVP API using the programming language of your
choice. This is the most straightforward and flexible approach. You can download web
samples that show how to integrate directly using PHP, Classic ASP, and ColdFusion.
For more information, see Appendix C, “NVP API Web Samples.”
Integrate Using an SDK

You can integrate with the NVP API using a software development kit (SDK). SDKs are
provided for Java and ASP.NET. The SDKs provide simple functions for integrating with the
NVP API.

Name-Value Pair API Developer Guide and Reference

April 2007

9

Overview
Basic Steps

For details about the PayPal NVP SDK, see Appendix D, “The Java SDK” or Appendix E,
“The ASP.NET SDK.”
Samples

To help you get started with the PayPal NVP API, samples are provided at
https://www.paypal.com/IntegrationCenter/ic_nvp.html. Using the samples, you can send API
calls to the PayPal Sandbox test environment.

Basic Steps
This section describes the basic steps for programming with the PayPal NVP API.
During application development, your application communicates with the PayPal Sandbox test
environment. The following section, “Taking Your Application Live” on page 11, describes
how to move your application to the live PayPal environment.
N O T E : The

simplest way to get started is to download and try out the sample applications as
described in “Integrating with the PayPal API” on page 9.

Create a Web Application
Your NVP API implementation usually runs in a web application. You can write your own
application or use one of the samples as a starting point.

Get API Credentials
To access the PayPal API, you need API credentials, either an API signature or API certificate,
that identify you.
Use the following sample API signature and password in your sample programs that run in the
PayPal Sandbox test environment.
N O T E : If

you are using the samples, this signature is already in the code.

TABLE 1.1 Details of the Sample API Signature

10

API username

sdk-three_api1.sdk.com

API password

QFZCWN5HZM8VBG7Q

API signature

A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU

April 2007

Name-Value Pair API Developer Guide and Reference

Overview
Taking Your Application Live

Create and Post the Request
Create an NVP request string and post it to PayPal sandbox server. Add code to your web
application to do the following tasks:
1. URL-encode the name and value parameters in the request to ensure correct transmission
of all characters. This is described in “URL-Encoding” on page 13.
2. Construct the NVP API request string as described in “Request Format” on page 14. The
NVP format is described in “NVP Format” on page 12.
3. Post the NVP request to the PayPal Sandbox as described in “Posting Using HTTPS” on
page 16.

Interpret the Response
PayPal processes your request and posts back a reponse in NVP format. Add code to your web
application to do the following tasks:
1. Receive the HTTP post response, and extract the NVP string.
2. URL-decode the parameter values as described in “URL-Encoding” on page 13.
3. Take appropriate action for successful and failed reponses.

Taking Your Application Live
After you have finished coding and testing your application, deploy your application to the
live PayPal server using your PayPal business account and API credentials for that account.

Set Up a PayPal Business Account
When you are ready to deploy your application to the live PayPal server, create a PayPal
business account on www.paypal.com.

Set Up API Credentials
To use the APIs, you need a set of credentials to identify yourself to PayPal. Create an API
signature for your business account.
For instructions on setting up API credentials for the business account, go to
https://www.paypal.com/IntegrationCenter/ic_certificate.html.

Name-Value Pair API Developer Guide and Reference

April 2007

11

Overview
Technical Details
IMPO RTANT: If

you are using API signature, you must protect the API signature values 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.
The sample code does not store these values securely. The sample code
should never be used in production.

N O T E : While

API signature is recommended, you can also use API certificate.

Modify Your Code
In your application, change the following items from the PayPal Sandbox values to the live
PayPal server values:
z

The server address in the URL. (See “Posting Using HTTPS” on page 16.)

z

API credentials you set up in “Set Up API Credentials” on page 11.

Technical Details
This section describes details of the technologies used by the PayPal NVP API.

Request-Response Model
When you use the PayPal NVP API, you post an NVP request to PayPal, and PayPal posts
back an NVP response.
URL Format

The request and response are in URL-encoded format, which is defined by the Worldwide Web
Consortium (W3C). URL is defined as part of the URI specification. Find out more about URI
at http://www.w3.org/Addressing/.
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:
z

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

z

Name-value pairs are separated by an ampersand (&). For example:
FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore

z

12

The NVP string is URL-encoded.

April 2007

Name-Value Pair API Developer Guide and Reference

Overview
Technical Details
URL-Encoding

The request and response are URL-encoded. URL-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. For example, the following NVP
string:
NAME=Robert Moore&COMPANY=R. H. Moore & Associates

is URL-coded as follows:
NAME=Robert+Moore&COMPANY=R%2E+H%2E+Moore+%26+Associates

Use the following methods to URL-encode or URL-decode your NVP strings:
TABLE 1.2 URL-Encoding Methods
Language
ASP.NET

Classic
ASP

Java

PHP

ColdFusion

Method
Encode

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

Decode

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

Encode

Server.URLEncode

Decode

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

Encode

java.net.URLEncoder.encode

Decode

java.net.URLDecoder.decode

Encode

urlencode()

Decode

urldecode()

Encode

URLEncodedFormatstring [, charset ]

Decode

URLDecodeurlEncodedString[, charset])

Name-Value Pair API Developer Guide and Reference

April 2007

13

Overview
Technical Details

Request Format
Each NVP request consists of required and optional parameters and their values. Parameter
names are not case sensitive. The examples in this document use UPPERCASE for parameter
names and divide the parameters into required security parameters and body parameters.
TABLE 1.3 General Format of a Request
Required
Security
Parameters

USER=apiUsername&PWD=apiPassword&SIGNATURE=apiSignature
&SUBJECT=optionalThirdPartyEmailAddress&VERSION=2.3

The following parameters are always required:
USER
PWD
VERSION=2.3
N O T E : The examples show the required security parameters like this:

[requiredSecurityParameters]
Body
Parameters

&METHOD=methodName&otherRequiredAndOptionalParameters

In practice, you need to concatenate all parameters and values into a single URL-encoded
string. After the METHOD parameter, you can specify the parameters in any order.
Required Security Parameters

The required security parameters are described below. These are your PayPal API credentials.
TABLE 1.4 Required Security Parameters: API Credentials
Parameter

Value

USER

Required

Your PayPal API Username.

PWD

Required

Your PayPal API Password.

VERSION=2.3

Required

Version number of the NVP API service.

SIGNATURE

Optional

Your PayPal API signature string.
If you use an API certificate, do not include this parameter.

SUBJECT

Optional

Email address of a PayPal account that has granted you permission to
make this call.
Set this parameter only if you are calling an API on a different user’s
behalf.

IMPO RTANT: 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.
The sample code does not store these values securely. The sample code
should never be used in production.

14

April 2007

Name-Value Pair API Developer Guide and Reference

Overview
Technical Details

You may see sample code where these values are stored in an HTML form.
The following is an example of what you should NOT do in production:
...
API Parameters The request body must contain the name of the API method in the METHOD parameter. In addition, each method has required and optional parameters: METHOD=methodName&requiredAndOptionalParameters All API methods and their parameters are detailed in Appendix A, “NVP API Method and Field Reference.” Examples of use are in Chapter 2, “Accepting PayPal in Express Checkout,” and Chapter 3, “Back-Office Administration.” Response Format A response from the PayPal servers is a URL-encoded name-value pair string, just like the request, except it has the following general format. TABLE 1.5 General Format of a Successful Response Success Response Fields ACK=Success&TIMESTAMP=date/timeOfResponse &CORRELATIONID=debuggingToken&VERSION=2.300000 &BUILD=buildNumber The examples show the successful response header fields like this: [successResponseFields] API Response Fields &NAME1=value1&NAME2=value2&NAME3=value3&... Each response includes the ACK field. If the ACK field’s value is Success or SuccessWithWarning, you should process the API response fields. In a successful response, you can ignore all fields up to and including the BUILD field. The important fields begin after the BUILD field. The possible successful response fields for each method are detailed in Appendix A, “NVP API Method and Field Reference.” What you do with the fields depends on the particular API method you are calling, such as filling-in a FORM for your user, updating your database, and so on. Name-Value Pair API Developer Guide and Reference April 2007 15 Overview Technical Details Error Responses If the ACK value is Error or Warning, API response fields are not returned. An error response has the following general format. TABLE 1.6 Format of an Error Response Response Fields on Error ACK=Error&TIMESTAMP=date/timeOfResponse& CORRELATIONID=debuggingToken&VERSION=2.300000& BUILD=buildNumber&L_ERRORCODE0=errorCode& L_SHORTMESSAGE0=shortMessage L_LONGMESSAGE0=longMessage &L_SEVERITYCODE0=severityCode Multiple errors can be returned. Each set of errors has a different numeric suffix, starting with 0 and incremented by one for each error. For possible causes of errors and how to correct them, see the explanation of the specific error code, short message, and long message in Appendix B, “Error Message Reference.” ACK Parameter Values The following table lists values for the ACK parameter. TABLE 1.7 ACK Parameter Values Type of Response Value Successful response Success SuccessWithWarning Error response Error Warning Posting Using HTTPS Your web application posts the URL-encoded NVP string over an HTTPS connection to one of the PayPal API servers. PayPal provides a live server and a Sandbox server that allows you to process transactions in a test environment. API Servers for API Signature Security If you use an API signature, post the request to one of these servers: Sandbox: https://api-3t.sandbox.paypal.com/nvp Live: https://api-3t.paypal.com/nvp API Servers for API Certificate Security If you use an API certificate, post the request to one of these servers: Sandbox: https://api.sandbox.paypal.com/nvp Live: https://api.paypal.com/nvp 16 April 2007 Name-Value Pair API Developer Guide and Reference 2 Accepting PayPal in Express Checkout By choosing Express Checkout, the customer can save time by skipping several checkout steps using the billing and shipping information stored on PayPal. This section describes how to use Express Checkout to accept payments using PayPal and contains the following topics: z “Basic Checkout with PayPal” on page 17 z “Controlling the Shipping Address Using SetExpressCheckout” on page 21 z “Changing the Language on the PayPal Login Page Using SetExpressCheckout” on page 23 z “Changing the Logo on the PayPal Pages Using SetExpressCheckout” on page 23 z “Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails” on page 24 z “Making a Sale Using DoExpressCheckoutPayment” on page 25 z “Changing the URL for IPN Using DoExpressCheckoutPayment” on page 25 z “Including Line Item Details Using DoExpressCheckoutPayment” on page 26 z “Including Subtotals Using DoExpressCheckoutPayment” on page 27 z “Updating Order Details Using DoExpressCheckoutPayment” on page 27 z “Updating the Shipping Address Using DoExpressCheckoutPayment” on page 28 Basic Checkout with PayPal N O T E : See the Integrationshandbuch Express-Kaufabwicklung for details on Express Checkout including page flow, integration points, button placement, and page design. Express Checkout with PayPal requires the following steps: 1. Starting the Checkout Using SetExpressCheckout 2. Redirecting the Customer’s Browser to PayPal Login Page 3. Getting Payer Details Using GetExpressCheckoutDetails 4. Making a Sale Using DoExpressCheckoutPayment In SetExpressCheckout response, you obtain a TOKEN that uniquely identifies this threestep transaction. You pass this TOKEN in the request to GetExpressCheckoutDetails and DoExpressCheckoutPayment. Both GetExpressCheckoutDetails and DoExpressCheckoutPayment return this TOKEN in the response. This example shows basic checkout using the minimum number of parameters. Name-Value Pair API Developer Guide and Reference April 2007 17 2 Accepting PayPal in Express Checkout Basic Checkout with PayPal 1. Starting the Checkout Using SetExpressCheckout The SetExpressCheckout request method notifies PayPal that you are using Express Checkout to obtain payment from your customer. You must always include the following parameters in SetExpressCheckout request: z AMT z RETURNURL z CANCELURL You are also advised to include the following parameters to ensure a smooth flow in case the funding methods giropay or electronic funds transfer are being used: z GIROPAYSUCCESSURL z GIROPAYFAILURL z BANKTXNPENDINGURL EXAMPLE 2.1 Starting the Checkout Request [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html Response [successResponseFields]&TOKEN=EC-3DJ78083ES565113B N O T E : Because we do not specify a value for PAYMENTACTION, this parameter defaults to Sale. Save TOKEN for use on the remaining Express Checkout calls. 2. Redirecting the Customer’s Browser to PayPal Login Page After you receive a successful response from SetExpressCheckout, add the TOKEN from SetExpressCheckout response as a name/value pair to the following URL, and redirect your customer’s browser to it: https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout& token=value_from_SetExpressCheckoutResponse For redirecting the customer’s browser to the PayPal login page, PayPal recommends that you use the HTTPS response 302 “Object Moved” with the URL above as the value of the Location header in the HTTPS response. Ensure that you use an SSL-enabled server to prevent browser warnings about a mix of secure and insecure graphics. 18 April 2007 Name-Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout Basic Checkout with PayPal 2 3. Getting Payer Details Using GetExpressCheckoutDetails The GetExpressCheckoutDetails method returns information about the customer, including name and address stored on PayPal. You must always include the following parameters in GetExpressCheckoutDetails: z TOKEN: use the value from SetExpressCheckout response The response contains this TOKEN and customer details. EXAMPLE 2.2 Getting Payer Details [requiredSecurityParameters]&METHOD=GetExpressCheckoutDetails& Request TOKEN=EC-3DJ78083ES565113B [successResponseFields]&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com& PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith& COUNTRYCODE=US&SHIPTONAME=John Smith&SHIPTOSTREET=144+Main+St.& SHIPTOCITY=San+Jose&SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=US& SHIPTOZIP=99221&ADDRESSID=PayPal& ADDRESSSTATUS=Confirmed Response Make sure TOKEN matches the value in SetExpressCheckout response. Save PAYERID for use on the next call. 4. Making a Sale Using DoExpressCheckoutPayment Request to obtain payment with PayPal Express Checkout using DoExpressCheckoutPayment request. By default, you make a final sale with DoExpressCheckoutPayment request. You must always include the following parameters in DoExpressCheckoutPayment request: z TOKEN: use the value from GetExpressCheckoutDetails response z PAYERID: use the value from GetExpressCheckoutDetails response z PAYMENTACTION: set to Sale. This is the default value in SetExpressCheckout. z AMT: use the same value as in SetExpressCheckout request EXAMPLE 2.3 Making a Sale Request [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-0E881823PA052770A&AMT=10.00& PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale Name-Value Pair API Developer Guide and Reference April 2007 19 2 Accepting PayPal in Express Checkout Support giropay and electronic funds transfer Response [successResponseFields&TOKEN=EC-0E881823PA052770A& TRANSACTIONID=8SC56973LM923823H&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T20:16:05Z&AMT=10.00& CURRENCYCODE=USD&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None Support giropay and electronic funds transfer Initiate the Flow with SetExpressCheckout To support giropay payments, you pass the following three URLs as part of the SetExpressCheckout request. These URLs tell PayPal where to redirect the customer based on the success or failure of each type of payment transaction. TABLE 2.1 SetExpressCheckout fields for giropay NVP SOAP Description Required? GIROPAYSUCCESSURL giropaySuccessURL The URL on the merchant site to redirect to after a successful giropay payment. No GIROPAYCANCELURL giropayCancelURL The URL on the merchant site to redirect to after a giropay or bank transfer payment is cancelled or fails. No BANKTXNPENDINGURL BanktxnPendingURL The URL on the merchant site to transfer to after a bank transfer payment. No Redirecting the Customer to PayPal After selecting a funding source on PayPal, the customer is redirected back to your website, as in the regular Express Checkout flow. There is one additional field, REDIRECTREQUIRED, returned in the response from both GetExpressCheckoutDetails and DoExpressCheckoutPayment. If the value of this field is true, you redirect the customer from your Order Review page to https://www.paypal.com/webscr?cmd=_complete-express-checkout&token=TOKEN . Append the token that you received in SetExpressCheckout. PayPal then redirects the customer from this redirect page to the necessary page for the selected funding source. 20 April 2007 Name-Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout Controlling the Shipping Address Using SetExpressCheckout 2 Completing the Transaction Corresponding the three fields passed to SetExpressCheckout (see Table 2.1, “SetExpressCheckout fields for giropay”), you must add the following three additional pages to your website: TABLE 2.2 Additional pages required for giropay integration Page Description Order Completion The page to redirect the customer to after a successful giropay payment. Order Cancellation The page to redirect the customer to after a giropay or bank-transfer payment is cancelled or fails Order Pending The page to redirect the customer to after a bank-transfer payment. Controlling the Shipping Address Using SetExpressCheckout You can make changes to the behavior of the shipping address with the REQCONFIRMSHIPPING, NOSHIPPING, and ADDROVERRIDE parameters in SetExpressCheckout request. N O T E : The shipping address is specified in the SHIPTOxxx parameters. Suppressing Display of Shipping Address on PayPal To suppress the display of the customer’s shipping address on the PayPal web pages, set NOSHIPPING to 1 in SetExpressCheckout request. You might want to do this if you are selling a product or service that does not require shipping. EXAMPLE 2.1 Suppressing the Shipping Address Request [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &NOSHIPPING=1 Response [successResponseFields]&TOKEN=EC-17C76533PL706494P Name-Value Pair API Developer Guide and Reference April 2007 21 2 Accepting PayPal in Express Checkout Controlling the Shipping Address Using SetExpressCheckout GetExpressCheckoutDetails does not return the shipping address. EXAMPLE 2.2 GetExpressCheckoutDetails Request [requiredSecurityParameters]&METHOD=GetExpressCheckoutDetails& TOKEN=EC-17C76533PL706494P [successResponseFields]&TOKEN=ECResponse 17C76533PL706494P&EMAIL=abcdef@anycompany.com&PAYERID=95HR9CM6D56Q2& PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith&COUNTRYCODE=US& ADDRESSID=PayPal&ADDRESSSTATUS=None Overriding the Shipping Address Stored on PayPal To override the shipping address stored on PayPal, call SetExpressCheckout to set ADDROVERRIDE to 1 and set the shipping address fields (see Table A.3, “Ship to Address (Optional)”). The customer cannot edit the address if it has been overridden. EXAMPLE 2.3 Overriding the Shipping Address Request [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &SHIPTONAME=Peter+Smith&SHIPTOSTREET=144+Main+St.&SHIPTOCITY=SAN+JOSE &SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=US&SHIPTOZIP=99911& ADDROVERRIDE=1 Response [successResponseFields]&TOKEN=EC-17C76533PL706494P GetExpressCheckoutDetails returns the overridden shipping address. EXAMPLE 2.4 GetExpressCheckoutDetails Request [requiredSecurityParameters]&METHOD=GetExpressCheckoutDetails&TOKEN=EC17C76533PL706494P [successResponseFields]&TOKEN=EC-17C76533PL706494P& Response 22 PAYER=abcdef@anycompany.com&PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified& FIRSTNAME=John&LASTNAME=Smith& COUNTRYCODE=US&SHIPTONAME=Peter+Smith&SHIPTOSTREET=144+Main+St.& SHIPTOCITY=SAN+JOSE&SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=US&SHIPTOZIP=95112& ADDRESSID=PayPal&ADDRESSSTATUS=Unconfirmed April 2007 Name-Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout Changing the Language on the PayPal Login Page Using SetExpressCheckout 2 Changing the Language on the PayPal Login Page Using SetExpressCheckout To change the language displayed on the PayPal login page, set LOCALECODE to one of the allowable values in SetExpressCheckout. For LOCALECODE values, see Table A.2, “SetExpressCheckout Request Parameters”. The following example sets LOCALECODE to French. EXAMPLE 2.5 Changing the PayPal Login Page Language to French Request [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& CURRENCYCODE=EUR& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &LOCALECODE=fr_FR Response [successResponseFields]&TOKEN=EC-17C76533PL706494P Changing the Logo on the PayPal Pages Using SetExpressCheckout You can modify the logo and other color settings on the PayPal pages in two ways: z Specifying a predefined Custom Payment Page Style z Setting logo and color settings individually Specifying a Custom Payment Page Style You can set the Custom Payment Page Style for the PayPal pages by setting the PAGESTYLE parameter in SetExpressCheckout. Set PAGESTYLE to one of the Page Style Names you defined in your Custom Payment Pages on https://www.paypal.com. The following example sets PAGESTYLE to DesignerFotos-Yellow in the SetExpressCheckout method EXAMPLE 2.6 Specifying a Custom Payment Page Style Request [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html& PAGESTYLE=DesignerFotos-Yellow Response [successResponseFields]&TOKEN=EC-17C76533PL706494P Name-Value Pair API Developer Guide and Reference April 2007 23 2 Accepting PayPal in Express Checkout Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails Specifying Logo and Color Settings Individually You can modify the PayPal web pages to look like your own web pages by setting the following parameters in SetExpressCheckout: z HDRIMG: specify an image to appear at the top left of the payment page z HDRBORDERCOLOR: set the border color around the header of the payment page z z HDRBACKCOLOR: set the background color for the background of the header of the payment page PAYFLOWCOLOR: set the background color for the payment page EXAMPLE 2.7 Specifying Logo and Color Settings Individually Request [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html& HDRIMG=https://www.anycompany.com/images/HeaderImage.gif& HDRBORDERCOLOR=3366FF&HDRBACKCOLOR=D3EFF5&PAYFLOWCOLOR=F8F5F5 Response [successResponseFields]&TOKEN=EC-17C76533PL706494P Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails Use the payer name and shipping address returned by GetExpressCheckoutDetails response to fill in form fields on your payment review page which you display after the customer returns from PayPal. EXAMPLE 2.8 Form-Filling Your Payment Review Page Request [requiredSecurityParameters]&METHOD=GetExpressCheckoutDetails& TOKEN=EC-3DJ78083ES565113B [successResponseFields]&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com& Response 24 PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith& COUNTRYCODE=US&SHIPTONAME=John Smith&SHIPTOSTREET=144+Main+St.& SHIPTOCITY=San+Jose&SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=US&SHIPTOZIP=99221& ADDRESSID=PayPal&ADDRESSSTATUS=Confirmed April 2007 Name-Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout Making a Sale Using DoExpressCheckoutPayment 2 Get the payer name from the following parameters in GetExpressCheckoutDetails response: z SALUTATION z FIRSTNAME z MIDDLENAME z LASTNAME z SUFFIX Get the shipping address from the following parameters in GetExpressCheckoutDetails response: z SHIPTONAME z SHIPTOSTREET z SHIPTOSTREET2 z SHIPTOCITY z SHIPTOSTATE z SHIPTOCOUNTRYCODE z SHIPTOPHONENUM z SHIPTOZIP Making a Sale Using DoExpressCheckoutPayment Use DoExpressCheckoutPayment to make a final sale. For more information, see “Basic Checkout with PayPal” on page 17. Changing the URL for IPN Using DoExpressCheckoutPayment You can change the URL for receiving Instant Payment Notification (IPN) about this transaction by setting the NOTIFYURL parameter in DoExpressCheckoutPayment. N O T E : If you do not specify this value in the request, the notification URL from your Merchant Profile is used, if one exists. For more information about IPN, see the Order Management Integration Guide. EXAMPLE 2.9 Changing the URL for IPN Request [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-8AX1275942659774U&PAYERID=95HR9CM6D56Q2&AMT=10.00& PAYMENTACTION=Sale&NOTIFYURL=https://www.anycompany.com/process-ipn/ Name-Value Pair API Developer Guide and Reference April 2007 25 2 Accepting PayPal in Express Checkout Including Line Item Details Using DoExpressCheckoutPayment [successResponseFields]&TOKEN=EC-8AX1275942659774U& TRANSACTIONID=1MA55216691247718&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:39:13Z&AMT=10.00& CURRENCYCODE=USD&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None Response Including Line Item Details Using DoExpressCheckoutPayment You can include line item details by setting the following parameters in DoExpressCheckoutPayment: z L_NAMEn: item name or description z L_NUMBERn: line item number z L_QTYn: item quantity z L_TAXAMTn: sales tax for the item z L_AMTn: cost of item You can detail as many items as you want. Beginning with 0, append an index number to the field name and increment that index number by one for each item. The following example sets line item details for two items. These details are recorded on PayPal. EXAMPLE 2.10 Including Line Item Details Request [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-4XH62109C8044521N&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=6.24& ITEMAMT=5.75&TAXAMT=0.49&L_NUMBER0=1&L_NAME0=A+Tale+of+Two+Cities&L_AMT0=2.50& L_QTY0=1&L_TAXAMT0=0.21&L_NAME1=Oliver+Twist&L_NUMBER1=2&L_AMT1=3.25&L_QTY1=1& L_TAXAMT1=0.28 [successResponseFields]&TOKEN=EC-4XH62109C8044521N& Response TRANSACTIONID=77U91743M2649930P&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:49:50Z&AMT=6.24& CURRENCYCODE=USD&FEEAMT=0.48&TAXAMT=0.28&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None If you specify L_AMTn, you must specify the ITEMAMT parameter. The values for L_AMTn and L_QTYn should add up to the ITEMAMT. If you specify L_TAXAMTn, you must specify the TAXAMT parameter. The values for L_TAXAMTn and L_QTYn should add up to TAXAMT. 26 April 2007 Name-Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout Including Subtotals Using DoExpressCheckoutPayment 2 Here are examples of ITEMAMT and TAXAMT: ITEMAMT = (L_AMT0 * L_QTY0) + (L_AMT1 + L_QTY1) + L_AMT2 TAXAMT = (L_TAXAMT0 * L_QTY0) + (L_TAXAMT1 * L_QTY1) + L_TAXAMT2 N O T E : If the line item details do not add up to ITEMAMT or TAXAMT, the line item details are discarded, and the transaction is processed using the values of ITEMAMT or TAXAMT. The ACK value in the response is set to SuccessWithWarning. Including Subtotals Using DoExpressCheckoutPayment If you want the PayPal user to see subtotals of item cost, shipping charges, handling charges, and sales tax, include the following parameters in DoExpressCheckoutPayment: z ITEMAMT z SHIPPINGAMT z HANDLINGAMT z TAXAMT N O T E : Be sure that the summed values of ITEMAMT, SHIPPINGAMT, HANDLINGAMT, and TAXAMT equal the value of AMT. You cannot include a zero amount for any of these fields, and you must set all of them. EXAMPLE 2.11 Including Subtotals Request [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment TOKEN=EC-0EU150885J108392M&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=6.24& AMT=192.22&ITEMAMT=176.02&SHIPPINGAMT=14.34&HANDLINGAMT=1.10&TAXAMT=0.76 [successResponseFields]&TOKEN=EC- Response 0EU150885J108392M&TRANSACTIONID=29W817045L6797418&TRANSACTIONTYPE=expresscheck out&PAYMENTTYPE=instant&ORDERTIME=2006-0823T16:20:22Z&AMT=192.22&CURRENCYCODE=USD&FEEAMT=5.87&TAXAMT=0.76&PAYMENTSTATUS =Completed&PENDINGREASON=None&REASONCODE=None Updating Order Details Using DoExpressCheckoutPayment You may need to update order details on PayPal if the customer makes a change to the order after returning to your order review page. If the change causes new values for one or more of the following parameters, you need to update the order details on PayPal using DoExpressCheckoutPayment: Name-Value Pair API Developer Guide and Reference April 2007 27 2 Accepting PayPal in Express Checkout Updating the Shipping Address Using DoExpressCheckoutPayment z DESC: item description z CUSTOM: field for your own use z INVNUM: your invoice or tracking number These three parameters may have been set in SetExpressCheckout. EXAMPLE 2.12 Updating Order Details [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC5JA9268562132991T&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=10.00& DESC=Order+for+5+books&CUSTOM=Thank+you+for+your+business!&INVNUM=ABC1234567 Request [successResponseFields]&TOKEN=EC5JA9268562132991T&TRANSACTIONID=9JJ517146A732773R&TRANSACTIONTYPE=expresscheck out&PAYMENTTYPE=instant&ORDERTIME=2006-0823T16:14:54Z&AMT=10.00&CURRENCYCODE=USD&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS= Completed&PENDINGREASON=None&REASONCODE=None Response Updating the Shipping Address Using DoExpressCheckoutPayment You may need to update the shipping address on PayPal if the customer updates the shipping address after returning to your order review page. If this happens, you need to update the shipping address for this transaction on PayPal. You can update the shipping address by setting the following parameters in DoExpressCheckoutPayment: 28 z SHIPTONAME z SHIPTOSTREET z SHIPTOSTREET2 z SHIPTOCITY z SHIPTOSTATE z SHIPTOCOUNTRYCODE z SHIPTOPHONENUM z SHIPTOZIP April 2007 Name-Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout Updating the Shipping Address Using DoExpressCheckoutPayment 2 EXAMPLE 2.13 Updating the Shipping Address [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& Request METHOD=DoExpressCheckoutPayment&TOKEN=EC-47C20533CU265432F& PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=10.00& SHIPTONAME=Michael+Brown&SHIPTOSTREET=22+First+Street&SHIPTOCITY=Chicago& SHIPTOCOUNTRYCODE=US&SHIPTOSTATE=IL&SHIPTOZIP=60605 [successResponseFields]&TOKEN=EC-47C20533CU265432F& Response TRANSACTIONID=59L39584YA765250B&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-23T16:08:12Z&AMT=10.00& CURRENCYCODE=USD&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None Name-Value Pair API Developer Guide and Reference April 2007 29 2 30 Accepting PayPal in Express Checkout Updating the Shipping Address Using DoExpressCheckoutPayment April 2007 Name-Value Pair API Developer Guide and Reference 3 Back-Office Administration This section gives you examples of the following functions: z “Refunding Using RefundTransaction” on page 31 z “Searching for Transactions Using TransactionSearch” on page 32 z “Viewing Details of a Single Transaction Using GetTransactionDetails” on page 33 Refunding Using RefundTransaction With RefundTransaction, you can refund the full amount or a partial amount of a transaction. Specify the original transaction ID and the refund type: Full or Partial. Full Refund IMPO RTANT: If you refund the full amount, do not set the AMT field. EXAMPLE 3.1 Refunding the Full Amount of a Transaction [requiredSecurityParameters]&METHOD=RefundTransaction&TRANSACTIONID=01945456967386 Request Response 7 &REFUNDTYPE=Full [successResponseFields]&REFUNDTRANSACTIONID=4RP55200GJ177180N &FEEREFUNDAMT=4.01&GROSSREFUNDAMT=127.87&NETREFUNDAMT=123.86 Partial Refunds To refund a partial amount, set REFUNDTYPE to Partial and set the AMT. EXAMPLE 3.2 Refunding A Partial Amount Request Response [requiredSecurityParameters]&METHOD=RefundTransaction &TRANSACTIONID=9CX07910UV614511L&REFUNDTYPE=Partial&AMT=12.95 [successResponseFields]&REFUNDTRANSACTIONID=1H0011898K637700R &FEEREFUNDAMT=0.38&GROSSREFUNDAMT=12.95&NETREFUNDAMT=12.57 Name-Value Pair API Developer Guide and Reference April 2007 31 3 Back-Office Administration Searching for Transactions Using TransactionSearch Including a Note with the Refund Whether the refund is full or partial, you can also include a note about the refund. EXAMPLE 3.3 Including a Note with the Refund Request Response [requiredSecurityParameters]&METHOD=RefundTransaction&TRANSACTIONID=01945456967386 7 &REFUNDTYPE=Partial&AMT=12.95&NOTE=Customer+changed+mind. [successResponseFields]&REFUNDTRANSACTIONID=1H0011898K637700R &FEEREFUNDAMT=0.38&GROSSREFUNDAMT=12.95&NETREFUNDAMT=12.57 Searching for Transactions Using TransactionSearch To find all transactions that occurred on a particular date, use TransactionSearch and set the STARTDATE field to the date you desire. The date must be in UTC/GMT format. EXAMPLE 3.4 Searching for Transactions by STARTDATE Request [requiredSecurityParameters]&METHOD=TransactionSearch &STARTDATE=2006-08-15T17:00:00Z [successResponseFields]&L_TIMESTAMP0=2006-08-18T05:58:41Z& Respons L_TIMEZONE0=GMT&L_TYPE0=Authorization&L_NAME0=John+Doe& L_TRANSACTIONID0=3XK029742B016373C&L_STATUS0=Pending&L_AMT0=1.00& L_TIMESTAMP1=2006-08-18T05:56:20Z&L_TIMEZONE1=GMT&L_TYPE1=Payment& L_NAME1=John+Doe&L_TRANSACTIONID1=4BV19600WF261673U&L_STATUS1=Completed &L_AMT1=1.00&L_FEEAMT1=-0.33&L_NETAMT1=0.67& L_TIMESTAMP2=2006-08-18T05:53:22Z&L_TIMEZONE2=GMT&L_TYPE2=Payment &L_NAME2=John+Doe&L_TRANSACTIONID2=6XB50622KC566325C&L_STATUS2=Completed &L_AMT2=1.00&L_FEEAMT2=-0.33&L_NETAMT2=0.67& L_TIMESTAMP3=2006-08-18T05:38:04Z&L_TIMEZONE3=GMT &L_TYPE3=Payment&L_NAME3=John+Doe&L_TRANSACTIONID3=80774637LP956560E& L_STATUS3=Completed&L_AMT3=1.00&L_FEEAMT3-0.33&L_NETAMT3=0.67& L_TIMESTAMP4=2006-08-17T03:02:44Z&L_TIMEZONE4=GMT&L_TYPE4=Payment& L_NAME4=Pettibone+Smythe-Jones&L_TRANSACTIONID4=8G40321568512733L& L_STATUS4=Completed&L_AMT4=104.00&L_FEEAMT4=-3.32&L_NETAMT4=100.68 TransactionSearch returns a multi-valued array of all transactions that match the search criteria. Each transaction begins with its date: L_TIMESTAMPn, where n starts with 0 and increments by one for each transaction. 32 April 2007 Name-Value Pair API Developer Guide and Reference Back-Office Administration Viewing Details of a Single Transaction Using GetTransactionDetails 3 Vi e w i n g D e ta i l s o f a S i n g l e Tr a n s a c t i o n U s i n g G e t Tr a n s a c t i o n D e ta i l s To view all details about a single transaction, use GetTransactionDetails. EXAMPLE 3.5 Viewing A Transaction’s Details Request [requiredSecurityParameters]&METHOD=GetTransactionDetails &TRANSACTIONID=3B288546P5019992D [successResponseFields]&RECEIVERBUSINESS=Jims+Hardware Response &RECEIVEREMAIL=jim@hardwareplace.com&RECEIVERID=WNSJNN89XVWFA &PAYERID=B3KS3VFYNG9SN&PAYERSTATUS=unverified&FIRSTNAME=James& LASTNAME=Biguy&COUNTRYCODE=US&SHIPTOSTATE=&ADDRESSID=PayPal&ADDRESSSTATUS=None &TRANSACTIONID=3B288546P5019992D&RECEIPTID=3596-6202-14612615 &TRANSACTIONTYPE=webaccept&PAYMENTTYPE=instant& ORDERTIME=2006-08-15T17:00:00Z&AMT=127.87&CURRENCYCODE=USD&FEEAMT=4.01 &TAXAMT=0.00&PENDINGREASON=None&REASONCODE=None&SALESTAX=0.00&L_QTY0=1 Name-Value Pair API Developer Guide and Reference April 2007 33 3 34 Back-Office Administration Viewing Details of a Single Transaction Using GetTransactionDetails April 2007 Name-Value Pair API Developer Guide and Reference A NVP API Method and Field Reference General Characteristics of Requests and Parameters Parameters The request parameter string follows the query component syntax defined in Uniform Resource Identifier (URI): Generic Syntax. Parameter names and their values can be upper- or lowercase. We show parameter names in uppercase for clarity. All values must be URL-encoded. Multi-Value Fields Fields that accept multiple values have names like this: L_FIELDNAMEn where L_ is literal, FIELDNAME is the name of the parameter, and n is an index number, starting at 0 and incremented by one for each value of the field. Index numbers must be sequential. For example, if an order contains multiple items, you can add an item cost for each item using the L_AMTn parameter: L_AMT0=4.95&L_AMT1=6.72&L_AMT2=7.95 PayPal-Supported Transactional Currencies The following currencies are supported by PayPal for use in transactions. TABLE A.1 PayPal-Supported Currencies and Currency Codes for Transactions ISO-4217 Code Currency AUD Australian Dollar CAD Canadian Dollar CHF Swiss Franc CZK Czech Koruna DKK Danish Krone EUR Euro GBP Pound Sterling Name-Value Pair API Developer Guide and Reference April 2007 35 NVP API Method and Field Reference Express Checkout TABLE A.1 PayPal-Supported Currencies and Currency Codes for Transactions ISO-4217 Code Currency HKD Hong Kong Dollar HUF Hungarian Forint JPY Japanese Yen NOK Norwegian Krone NZD New Zealand Dollar PLN Polish Zloty SEK Swedish Krona SGD Singapore Dollar USD U.S. Dollar Express Checkout SetExpressCheckout Request TABLE A.2 SetExpressCheckout Request Parameters Parameter Description Required METHOD Name of the API: SetExpressCheckout Yes RETURNURL URL to which the customer’s browser is returned after choosing to pay with PayPal. Yes N O T E : PayPal recommends that the value be the final review page on which the customer confirms the order and payment. Character length and limitations: no limit. CANCELURL URL to which the customer is returned if he does not approve the use of PayPal to pay you. Yes N O T E : PayPal recommends that the value be the original page on which the customer chose to pay with PayPal. Character length and limitations: no limit GIROPAYSUCCESSURL 36 URL of your website where the user gets redirected once he successfully completed a transaction with giropay. This page should be the order confirmation page. April 2007 No (recommended) Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout TABLE A.2 SetExpressCheckout Request Parameters (Continued) Parameter Description Required GIROPAYCANCELURL URL of your website where the user gets redirected when a giropay or electronic funds transfer transaction fails. No (recommended) BANKTXNPENDINGURL URL of your website where the user gets redirected when he has initiated an electronic funds transfer. No (recommended) AMT The total cost of the order to the customer. If shipping cost and tax charges are known, include them in this value; if not, this value should be the current sub-total of the order. Yes N O T E : Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). CURRENCYCODE A three-character currency code for one of the currencies listed in PayPal-Supported Transactional Currencies. Default: USD. No MAXAMT The expected maximum total amount of the complete order, including shipping cost and tax charges. No N O T E : Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). PAYMENTACTION How you want to obtain payment: z Sale indicates that this is a final sale for which you are requesting payment. Character length and limit: Up to 13 single-byte alphabetic characters Allowable Values: z Authorization z Order z Sale Default: The transaction resulting from DoExpressCheckoutPayment request will be a final sale.. No EMAIL Email address of the buyer as entered during checkout. PayPal uses this value to pre-fill the PayPal membership sign-up portion of the PayPal login page. Character length and limit: 127 single-byte alphanumeric characters No DESC Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters No Name-Value Pair API Developer Guide and Reference April 2007 37 NVP API Method and Field Reference Express Checkout TABLE A.2 SetExpressCheckout Request Parameters (Continued) Parameter Description Required CUSTOM A free-form field for your own use, such as a tracking number or other value you want PayPal to return on GetExpressCheckoutDetails response and DoExpressCheckoutPayment response. Character length and limitations: 256 single-byte alphanumeric characters No INVNUM Your own unique invoice or tracking number. PayPal returns this value to you on DoExpressCheckoutPayment response. Character length and limitations: 127 single-byte alphanumeric characters No REQCONFIRMSHIPPING The value 1 indicates that you require that the customer’s shipping address on file with PayPal be a confirmed address. No N O T E : Setting this field overrides the setting you have specified in your Merchant Account Profile. Character length and limitations: One single-byte numeric character. Allowable values: 0, 1 Default: 0 NOSHIPPING The value 1 indicates that on the PayPal pages, no shipping address fields should be displayed whatsoever. Character length and limitations: Four single-byte numeric character. Allowable values: 0, 1 Default: 0 No ADDROVERRIDE The value 1 indicates that the PayPal pages should display the shipping address set by you in this SetExpressCheckout request, not the shipping address on file with PayPal for this customer. No N O T E : Displaying the PayPal street address on file does not allow the customer to edit that address. Allowable values: 0, 1 Default: 0 TOKEN A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout. No N O T E : The token expires after three hours. If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. Character length and limitations: 20 single-byte characters Allowable values: See the description of TOKEN in Table A.4, “SetExpressCheckout Response Fields.” 38 April 2007 Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout TABLE A.2 SetExpressCheckout Request Parameters (Continued) Parameter Description Required LOCALECODE Locale of pages displayed by PayPal during Express Checkout. Character length and limitations: Any two-character country code. The following two-character country codes are supported by PayPal: z AU z DE z FR z IT z GB z ES z US Any other value will default to US. No N O T E : For the list of country codes, see Appendix Codes.” F, “Country PAGESTYLE Sets the Custom Payment Page Style for payment pages associated with this button/link. This value corresponds to the HTML variable page_style for customizing payment pages. The value is the same as the Page Style Name you chose when adding or editing the page style from the Profile subtab of the My Account tab of your PayPal account. Character length and limitations: 30 single-byte alphabetic characters. No HDRIMG A URL for the image you want to appear at the top left of the payment page. The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal recommends that you provide an image that is stored on a secure (https) server. Character length and limitations: 127 No HDRBORDERCOLOR Sets the border color around the header of the payment page. The border is a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels high. Character length and limitations: Six character HTML hexadecimal color code in ASCII No HDRBACKCOLOR Sets the background color for the header of the payment page. Character length and limitation: Six character HTML hexadecimal color code in ASCII No PAYFLOWCOLOR Sets the background color for the payment page. Character length and limitation: Six character HTML hexadecimal color code in ASCII No Name-Value Pair API Developer Guide and Reference April 2007 39 NVP API Method and Field Reference Express Checkout TABLE A.2 SetExpressCheckout Request Parameters (Continued) Parameter Description Required Shipping Address Optional shipping address. The parameters for the optional Ship to Address are described in Table A.3, “Ship to Address (Optional).” No I M P O R T A N T : Ship to Address is optional, but if you include it, certain fields are required. TABLE A.3 40 Ship to Address (Optional) Parameter Description Required SHIPTONAME Person’s name associated with this shipping address. Character length and limitations: 32 single-byte characters Yes SHIPTOSTREET First street address. Character length and limitations: 100 single-byte characters Yes SHIPTOCITY Name of city. Character length and limitations: 40 single-byte characters Yes SHIPTOSTATE State or province. Character length and limitations: 40 single-byte characters Yes SHIPTOCOUNTRYCODE Country code. Character limit: Two single-byte characters. For the list of country codes, see Appendix F, “Country Codes.” Yes SHIPTOZIP U.S. Zip code or other country-specific postal code. Character length and limitations: 20 single-byte characters Yes SHIPTOSTREET2 Second street address. Character length and limitations: 100 single-byte characters No PHONENUM Phone number. Character length and limit: 20 single-byte characters No April 2007 Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout SetExpressCheckout Response TABLE A.4 SetExpressCheckout Response Fields Parameter Description TOKEN A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout. N O T E : The token expires after three hours. If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. Character length and limitations: 20 single-byte characters Redirecting the Customer’s Browser to PayPal Login Page After you receive a successful response from SetExpressCheckout, add the TOKEN from SetExpressCheckout response as a name/value pair to the following URL, and redirect your customer’s browser to it: https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout& token=value_from_SetExpressCheckoutResponse For redirecting the customer’s browser to the PayPal login page, PayPal recommends that you use the HTTPS response 302 “Object Moved” with the URL above as the value of the Location header in the HTTPS response. Ensure that you use an SSL-enabled server to prevent browser warnings about a mix of secure and insecure graphics. GetExpressCheckoutDetails Request TABLE A.5 GetExpressCheckoutDetails Parameters Parameter Description Required? METHOD Name of the API: GetExpressCheckoutDetails Yes TOKEN A timestamped token, the value of which was returned by SetExpressCheckout response. Character length and limitations: 20 single-byte characters Allowable values: An unexpired token Yes Name-Value Pair API Developer Guide and Reference April 2007 41 NVP API Method and Field Reference Express Checkout GetExpressCheckoutDetails Response TABLE A.6 GetExpressCheckoutDetails Response Fields Field Description TOKEN The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations: 20 single-byte characters Possible values: See the description of TOKEN in Table A.4, “SetExpressCheckout Response Fields.” EMAIL Email address of payer. Character length and limitations: 127 single-byte characters PAYERID Unique PayPal customer account identification number. Character length and limitations:13 single-byte alphanumeric characters. 42 PAYERSTATUS Status of payer. Character length and limitations: 10 single-byte alphabetic characters. Possible values: verified, unverified SALUTATION Payer’s salutation. Character length and limitations: 20 single-byte characters FIRSTNAME Payer’s first name. Character length and limitations: 25 single-byte characters MIDDLENAME Payer’s middle name. Character length and limitations: 25 single-byte characters LASTNAME Payer’s last name. Character length and limitations: 25 single-byte characters SUFFIX Payer’s suffix. Character length and limitations: 12 single-byte characters COUNTRYCODE Payer’s country of residence in the form of ISO standard 3166 two-character country codes. Character length and limitations: Two single-byte characters For the list of country codes, see Appendix F, “Country Codes.” BUSINESS Payer’s business name. Character length and limitations: 127 single-byte characters SHIPTONAME Person’s name associated with this address. Character length and limitations: 32 single-byte characters SHIPTOSTREET First street address. Character length and limitations: 100 single-byte characters April 2007 Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout TABLE A.6 GetExpressCheckoutDetails Response Fields (Continued) Field Description SHIPTOSTREET2 Second street address. Character length and limitations: 100 single-byte characters SHIPTOCITY Name of city. Character length and limitations: 40 single-byte characters SHIPTOSTATE State or province Character length and limitations: 40 single-byte characters SHIPTOCOUNTRYCODE Country code. Character limit: Two single-byte characters. For the list of country codes, see Appendix F, “Country Codes.” SHIPTOZIP U.S. Zip code or other country-specific postal code. Character length and limitations: 20 single-byte characters ADDRESSSTATUS Status of street address on file with PayPal CUSTOM A free-form field for your own use, as set by you in the Custom element of SetExpressCheckout request. Character length and limitations: 256 single-byte alphanumeric characters INVNUM Your own invoice or tracking number, as set by you in the element of the same name in SetExpressCheckout request . Character length and limitations: 127 single-byte alphanumeric characters PHONENUM Payer’s contact telephone number. N O T E : PayPal returns a contact telephone number only if your Merchant account profile settings require that the buyer enter one. Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers) or +XXX XXXXXXXX (for international numbers) REDIRECTREQUIRED If the value equals “True,” you must redirect the user after the DoExpressCheckout call. The value here indicates that you should inform your user on the Review Order page that he will be redirected to PayPal to complete the transaction. DoExpressCheckoutPayment Request Request to obtain payment with PayPal Express Checkout. IMPO RTANT: PayPal requires that a merchant using Express Checkout display to the customer the same amount that the merchant sends to PayPal in the AMT parameter with the DoExpressCheckoutPayment request API. Name-Value Pair API Developer Guide and Reference April 2007 43 NVP API Method and Field Reference Express Checkout TABLE A.7 DoExpressCheckoutPayment Parameters Parameter Description Required? METHOD Name of the API: DoExpressCheckoutPayment Yes TOKEN The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations: 20 single-byte characters Yes PAYMENTACTION How you want to obtain payment: z Sale indicates that this is a final sale for which you are requesting payment. Character length and limit: Up to 13 single-byte alphabetic characters Allowable Values: z Authorization z Order z Sale Default: The transaction resulting from DoExpressCheckoutPayment request will be a final sale.. Yes PAYERID Unique PayPal customer account identification number as returned by GetExpressCheckoutDetails response. Character length and limitations: 13 single-byte alphanumeric characters. Yes AMT Total of order, including shipping, handling, and tax. Yes N O T E : Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). 44 DESC Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters No CUSTOM A free-form field for your own use. Character length and limitations: 256 single-byte alphanumeric characters No INVNUM Your own invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters No BUTTONSOURCE An identification code for use by third-party applications to identify transactions. Character length and limitations: 32 single-byte alphanumeric characters No April 2007 Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout TABLE A.7 DoExpressCheckoutPayment Parameters (Continued) Parameter Description Required? NOTIFYURL Your URL for receiving Instant Payment Notification (IPN) about this transaction. No N O T E : If you do not specify this value in the request, the notification URL from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters ITEMAMT Sum of cost of all items in this order. No Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). N O T E : ITEMAMT is required if you specify a value for L_AMTn. SHIPPINGAMT Total shipping costs for this order. No N O T E : Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. HANDLINGAMT Total handling costs for this order. No N O T E : Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. TAXAMT Sum of tax for all items in this order. No N O T E : Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. N O T E : TAXAMT is required if you specify a value for L_TAXAMTn. CURRENCYCODE A three-character currency code for one of the currencies listed in PayPalSupported Transactional Currencies. Default: USD. No L_NAMEn Item name. No Character length and limitations: 127 single-byte characters These parameters should be ordered sequentially beginning with 0, for example, L_NAME0, L_NAME1, and so forth. Name-Value Pair API Developer Guide and Reference April 2007 45 NVP API Method and Field Reference Express Checkout TABLE A.7 DoExpressCheckoutPayment Parameters (Continued) Parameter Description Required? L_NUMBERn Item number. Character length and limitations: 127 single-byte characters No These parameters should be ordered sequentially beginning with 0, for example, L_NUMBER0, L_NUMBER1, and so forth. Item quantity. Character length and limitations: Any positive integer L_QTYn No These parameters should be ordered sequentially beginning with 0, for example, L_QTY0, L_QTY1, and so forth. No Item sales tax. L_TAXAMTn Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. These parameters should be ordered sequentially beginning with 0, for example, L_TAXAMT0, L_TAXAMT1, and so forth. No Cost of item L_AMTn Character length and limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. These parameters should be ordered sequentially beginning with 0, for example, L_AMT0, L_AMT1, and so forth. Shipping Address Optional shipping address. The parameters for the optional Ship to Address are described in Table A.8, “Optional Ship to Address.” No I M P O R T A N T : Ship to Address is optional, but if you include it, certain fields are required. TABLE A.8 46 Optional Ship to Address Parameter Description Required? SHIPTONAME Person’s name associated with this address. Character length and limitations: 32 single-byte characters Yes SHIPTOSTREET First street address. Character length and limitations: 100 single-byte characters Yes SHIPTOCITY Name of city. Character length and limitations: 40 single-byte characters Yes April 2007 Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout TABLE A.8 Optional Ship to Address (Continued) Parameter Description Required? SHIPTOSTATE State or province. Character length and limitations: 40 single-byte characters Yes SHIPTOCOUNTRYCODE Country code. Character limit: Two single-byte characters For the list of country codes, see Appendix F, “Country Codes.” Yes SHIPTOZIP U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters Yes SHIPTOSTREET2 Second street address. Character length and limitations: 100 single-byte characters No SHIPTOPHONENUM Phone number. Character length and limit: 20 single-byte characters No DoExpressCheckoutPayment Response TABLE A.9 DoExpressCheckout Payment Response Fields Field Description TOKEN The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations:20 single-byte characters Allowable values: See the description of TOKEN in Table A.4, “SetExpressCheckout Response Fields.” TRANSACTIONID Unique transaction ID of the payment. N O T E : If the PaymentAction of the request was Authorization or Order, this value is your AuthorizationID for use with the Authorization & Capture APIs. Character length and limitations:19 single-byte characters Possible values: Transaction specific TRANSACTIONTYPE The type of transaction Character length and limitations:15 single-byte characters Possible values: z cart z express-checkout Name-Value Pair API Developer Guide and Reference April 2007 47 NVP API Method and Field Reference Express Checkout TABLE A.9 DoExpressCheckout Payment Response Fields (Continued) Field Description PAYMENTTYPE Indicates whether the payment is instant or delayed. Character length and limitations: Seven single-byte characters Possible values: z none z echeck z instant ORDERTIME Time/date stamp of payment Possible values: Transaction specific AMT The final amount charged, including any shipping and taxes from your Merchant Profile. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. Possible Values: Transaction specific CURRENCYCODE A three-character currency code for one of the currencies listed in PayPay-Supported Transactional Currencies. Default: USD. FEEAMT PayPal fee amount charged for the transaction Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. Possible values: Transaction specific SETTLEAMT Amount deposited in your PayPal account after a currency conversion. Possible values: Transaction specific TAXAMT Tax charged on the transaction. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD. Possible values: Transaction specific EXCHANGERATE 48 Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency. If the customer chooses to pay with a currency other than the nonprimary currency, the conversion occurs in the customer’s account. Character length and limitations: a decimal that does not exceed 17 characters, including decimal point Possible values: Transaction specific April 2007 Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout TABLE A.9 DoExpressCheckout Payment Response Fields (Continued) Field Description PAYMENTSTATUS Status of the payment: Completed: The payment has been completed, and the funds have been added successfully to your account balance. Pending: The payment is pending. See the PendingReason element for more information. PENDINGREASON The reason the payment is pending: z none: No pending reason z address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile. z echeck: The payment is pending because it was made by an eCheck that has not yet cleared. z intl: The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview. z multi-currency: You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment. z verify: The payment is pending because you are not yet verified. You must verify your account before you can accept this payment. z other: The payment is pending for a reason other than those listed above. For more information, contact PayPal customer service. REASONCODE The reason for a reversal if TransactionType is reversal: z none: No reason code z chargeback: A reversal has occurred on this transaction due to a chargeback by your customer. z guarantee: A reversal has occurred on this transaction due to your customer triggering a money-back guarantee. z buyer-complaint: A reversal has occurred on this transaction due to a complaint about the transaction from your customer. z refund: A reversal has occurred on this transaction because you have given the customer a refund. z other: A reversal has occurred on this transaction due to a reason not listed above. REDIRECTREQUIRED If the value equals "True" you have to redirect the user to PayPal. PayPal will direct the user according to the selected payment methods (e.g. to giropay). When redirecting the user to Paypal you need to append the Token-value to the following redirect URL https://www.paypal.com/webscr?cmd=_complete-expresscheckout&token=TOKEN. TOKEN needs to equal the Token-value that you received in the SetExpressCheckoutResponse. Name-Value Pair API Developer Guide and Reference April 2007 49 NVP API Method and Field Reference RefundTransaction RefundTransaction TABLE A.10 RefundTransaction Request Parameters Parameter Description Required? METHOD Name of API call: RefundTransaction Yes TRANSACTIONID Unique identifier of a transaction Character length and limitations: 17 single-byte alphanumeric characters Yes REFUNDTYPE Type of refund you are making z Other z Full z Partial Yes AMT Refund amount. Amount is required if RefundType is Partial. No N O T E : If RefundType is Full, do not set Amount unless your merchant account has been enabled to issue refunds greater than the amount in referenced transactions. Custom memo about the refund. Character length and limitations: 255 single-byte alphanumeric characters NOTE No TABLE A.11 DoRefund Response Fields Field Description REFUNDTRANSACTIONID Unique transaction ID of the refund. Character length and limitations:17 single-byte characters NETREFUNDAMT Amount subtracted from PayPal balance of original recipient of payment to make this refund FEEREFUNDAMT Transaction fee refunded to original recipient of payment GROSSREFUNDAMT Amount of money refunded to original payer TransactionSearch With TransactionSearch you must always set the StartDate field. Some other behavior: 50 z Setting TransactionID overrides all other fields (even the required StartDate field). z The effect of setting other elements is additive or can alter the search criteria. April 2007 Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference TransactionSearch TransactionSearch returns up to 100 matches. Partial matches are displayed. For example, setting the TransactionSearchRequest FirstName to “Jess” returns results such as “Jessica” and “Jesse”. The most important returned element is TransactionID, which you can pass to GetTransactionDetails in order to retrieve all available information about a specific transaction. TABLE A.12 TransactionSearch Request Parameters Parameter Description Required METHOD Name of API call: TransactionSearch Yes STARTDATE The earliest transaction date at which to start the search. Yes N O T E : No wildcards are allowed. The value must be in UTC/GMT format. ENDDATE The latest transaction date to be included in the search No EMAIL Search by the buyer’s email address Character length and limitations: 127 single-byte alphanumeric characters No RECEIVER Search by the receiver’s email address. If the merchant account has only one email, this is the primary email. Can also be a non-primary email. No RECEIPTID Search by the PayPal Account Optional receipt ID No TRANSACTIONID Search by the transaction ID. No N O T E : The returned results are from the merchant’s transaction records. Character length and limitations: 19 single-byte characters maximum INVNUM Search by invoice identification key, as set by you for the original transaction. This field searches the records for items sold by the merchant, not the items purchased. No N O T E : No wildcards are allowed. Character length and limitations: 127 single-byte characters maximum ACCT Search by credit card number, as set by you for the original transaction. This field searches the records for items sold by the merchant, not the items purchased. No N O T E : No wildcards are allowed. Character length and limitations: Must be at least 11 and no more than 25 single-byte numeric characters maximum. Special punctuation, such as dashes or spaces, is ignored. SALUTATION Buyer’s salutation Character length and limitations: 20 single-byte characters No FIRSTNAME Buyer’s first name Character length and limitations: 25 single-byte characters No Name-Value Pair API Developer Guide and Reference April 2007 51 NVP API Method and Field Reference TransactionSearch TABLE A.12 TransactionSearch Request Parameters (Continued) Parameter Description Required MIDDLENAME Buyer’s middle name Character length and limitations: 25 single-byte characters No LASTNAME Buyer’s last name Character length and limitations: 2025 single-byte characters No SUFFIX Payer’s suffix Character length and limitations: 12 single-byte characters No AUCTIONITEMNUMBER Search by auction item number of the purchased goods No TRANSACTIONCLASS Search by classification of transaction. No N O T E : Some kinds of possible classes of transactions are not searchable with this field. You cannot search for bank transfer withdrawals, for example. z z z z z z z z z z z z z z z z z z z AMT 52 All: all transaction classifications Sent: only payments sent Received: only payments received MassPay: only mass payments MoneyRequest: only money requests FundsAdded: only funds added to balance FundsWithdrawn: only funds withdrawn from balance Referral: only transactions involving referrals Fee: only transactions involving fees Subscription: only transactions involving subscriptions Dividend: only transactions involving dividends Billpay: only transactions involving BillPay Transactions Refund: only transactions involving funds CurrencyConversions: only transactions involving currency conversions BalanceTransfer: only transactions involving balance transfers Reversal: only transactions involving BillPay reversals Shipping: only transactions involving UPS shipping fees BalanceAffecting: only transactions that affect the account balance ECheck: only transactions involving eCheck Search by transaction amount April 2007 No Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference TransactionSearch TABLE A.12 TransactionSearch Request Parameters (Continued) Parameter Description Required STATUS Search by transaction status: z Pending: The payment is pending. The specific reason the payment is pending is returned by the GetTransactionDetails API PendingReason field. z Processing: The payment is being processed. z Success: The payment has been completed and the funds have been added successfully to your account balance. z Denied: You denied the payment. This happens only if the payment was previously pending. z Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. No TABLE A.13 TransactionSearch Response Fields Field Description L_TIMESTAMPn The date and time (in UTC/GMT format) the transaction occurred These parameters should be ordered sequentially beginning with 0, for example, L_TIMESTAMP0, L_TIMESTAMP1, and so forth. L_TIMEZONEn The time zone of the transaction These parameters should be ordered sequentially beginning with 0, for example, L_TIMEZONE0, L_TIMEZONE1, and so forth. L_TYPEn The type of the transaction These parameters should be ordered sequentially beginning with 0, for example, L_TYPE0, L_TYPE1, and so forth. L_EMAILn The email address of either the payer or the payment recipient (the “payee”). If the payment amount is positive, this field is the recipient of the funds. If the payment is negative, this field is the paying customer. These parameters should be ordered sequentially beginning with 0, for example, L_EMAIL0, L_EMAIL1, and so forth. L_NAMEn Display name of the payer These parameters should be ordered sequentially beginning with 0, for example, L_NAME0, L_NAME1, and so forth. L_TRANSACTIONIDn Seller’s transaction ID These parameters should be ordered sequentially beginning with 0, for example, L_TRANSACTIONID0, L_TRANSACTIONID1, and so forth. L_STATUSn The status of the transaction. These parameters should be ordered sequentially beginning with 0, for example, L_STATUS0, L_STATUS1, and so forth. Name-Value Pair API Developer Guide and Reference April 2007 53 NVP API Method and Field Reference GetTransactionDetails TABLE A.13 TransactionSearch Response Fields (Continued) Field Description L_AMTn The total gross amount charged, including any profile shipping cost and taxes These parameters should be ordered sequentially beginning with 0, for example, L_AMT0, L_AMT1, and so forth. L_FEEAMTn The fee that PayPal charged for the transaction These parameters should be ordered sequentially beginning with 0, for example, L_FEEAMT0, L_FEEAMT1, and so forth. L_NETAMTn The net amount of the transaction These parameters should be ordered sequentially beginning with 0, for example, L_NETAMT0, L_NETAMT1, and so forth. GetTransactionDetails TABLE A.14 GetTransactionDetails Request Parameters Parameter Description Required? METHOD Name of the API: GetTransactionDetails Yes TRANSACTIONID Unique identifier of a transaction. Yes N O T E : The details for some kinds of transactions cannot be retrieved with GetTransactionDetails. You cannot obtain details of bank transfer withdrawals, for example. Character length and limitations: 17 single-byte alphanumeric characters TABLE A.15 GetTransactionDetails Response Fields 54 Parameter Description RECEIVERBUSINESS Email address or account ID of the payment recipient (the seller). Equivalent to Receiver if payment is sent to primary account. Character length and limitations: 127 single-byte alphanumeric characters RECEIVEREMAIL Primary email address of the payment recipient (the seller). If you are the recipient of the payment and the payment is sent to your non-primary email address, the value of Receiver is still your primary email address. Character length and limitations: 127 single-byte alphanumeric characters RECEIVERID Unique account ID of the payment recipient (the seller). This value is the same as the value of the recipient's referral ID. April 2007 Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference GetTransactionDetails TABLE A.15 GetTransactionDetails Response Fields (Continued) Parameter Description EMAIL Email address of payer Character length and limitations: 127 single-byte characters PAYERID Unique customer ID. Character length and limitations: 13 single-byte alphanumeric characters. PAYERSTATUS Status of payer’s email address: Verified Unverified FIRSTNAME Payer’s first name Character length and limitations: 25 single-byte characters LASTNAME Payer’s last name Character length and limitations: 25 single-byte characters MIDDLENAME Payer’s middle name Character length and limitations: 25 single-byte characters PAYERBUSINESS Payer’s business name. Character length and limitations: 127 single-byte characters SHIPTOCOUNTRYCODE Payment sender’s country of residence using standard two-character ISO 3166 country codes. Character length and limitations: Two single-byte characters For the list of country codes, see Appendix F, “Country Codes.” SALUTATION Payer’s salutation Character length and limitations: 20 single-byte characters SUFFIX Payer’s suffix Character length and limitations: 12 single-byte characters ADDRESSOWNER eBay company that maintains this address ADDRESSSTATUS Status of the address on file with PayPal: None Confirmed Unconfirmed SHIPTOCITY Name of city. Character length and limitations: 120 single-byte alphanumeric characters SHIPTONAME Person’s name associated with this address. Character length and limitations: 32 single-byte alphanumeric characters SHIPTOPHONENUM Phone number associated with this address SHIPTOZIP Postal code Name-Value Pair API Developer Guide and Reference April 2007 55 NVP API Method and Field Reference GetTransactionDetails TABLE A.15 GetTransactionDetails Response Fields (Continued) 56 Parameter Description SHIPTOSTATE State or province. Character length and limitations: 120 single-byte alphanumeric characters SHIPTOSTREET First street address. Character length and limitations: 300 single-byte alphanumeric characters SHIPTOSTREET2 Second street address. Character length and limitations: 300 single-byte alphanumeric characters PARENTTRANSACTIONID Original transaction to which this transaction is related. This field is populated for the following transaction types: z Reversal z Capture of an authorized transaction. z Reauthorization of a transaction. z Capture of an order. The value of ParentTransactionID is the original OrderID. z Authorization of an order. The value of ParentTransactionID is the original OrderID. z Capture of an order authorization. z Void of an order. The value of ParentTransactionID is the original OrderID. Character length and limitations: 19 single-byte characters TRANSACTIONID PayPal transaction identification number Character length and limitations: 19 single-byte characters RECEIPTID Receipt ID Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format TRANSACTIONTYPE The type of transaction cart: Transaction created by customer via the PayPal Shopping Cart feature. send-money: Transaction created by customer from the Send Money tab on the PayPal website. web-accept: Transaction created by customer via Buy Now, Donation, or Auction Smart Logos. subscr-*: Transaction created by customer via Subscription. eot means “end of subscription term.” merch-pmt: preapproved payment. mass-pay: Transaction created via MassPay. virtual-terminal: Transaction created via merchant virtual terminal. PAYMENTTYPE Indicates whether the payment is instant or delayed. Character length and limitations: Seven single-byte characters ORDERTIME Date and time of payment AMT Full amount of the customer’s payment, before transaction fee is subtracted April 2007 Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference GetTransactionDetails TABLE A.15 GetTransactionDetails Response Fields (Continued) Parameter Description FEEAMT Transaction fee associated with the payment SETTLEAMT Amount deposited into the account’s primary balance after a currency conversion from automatic conversion through your Payment Receiving Preferences or manual conversion through manually accepting a payment. This amount is calculated after fees and taxes have been assessed. TAXAMT Amount of tax for transaction EXCHANGERATE Exchange rate for transaction PAYMENTSTATUS Status of the payment. The status of the payment: z None: No status z Canceled-Reversal: This means a reversal has been canceled. For example, you won a dispute with the customer, and the funds for the transaction that was reversed have been returned to you. z Completed: The payment has been completed, and the funds have been added successfully to your account balance. z Denied: You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element. z Expired: the authorization period for this payment has been reached. z Failed: The payment has failed. This happens only if the payment was made from your customer’s bank account. z Pending: The payment is pending. See the PendingReason field for more information. z Refunded: You refunded the payment. z Reversed: A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the ReasonCode element. z Processed: A payment has been accepted. z Voided: An authorization for this transaction has been voided. Name-Value Pair API Developer Guide and Reference April 2007 57 NVP API Method and Field Reference GetTransactionDetails TABLE A.15 GetTransactionDetails Response Fields (Continued) Parameter Description PENDINGREASON N O T E : PendingReason is returned in the response only if PaymentStatus is Pending. The reason the payment is pending: z none: No pending reason z address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile. z echeck: The payment is pending because it was made by an eCheck that has not yet cleared. z intl: The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview. z multi-currency: You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment. z verify: The payment is pending because you are not yet verified. You must verify your account before you can accept this payment. z other: The payment is pending for a reason other than those listed above. For more information, contact PayPal Customer Service. 58 REASONCODE The reason for a reversal if TransactionType is reversal: z none: No reason code z chargeback: A reversal has occurred on this transaction due to a chargeback by your customer. z guarantee: A reversal has occurred on this transaction due to your customer triggering a money-back guarantee. z buyer-complaint: A reversal has occurred on this transaction due to a complaint about the transaction from your customer. z refund: A reversal has occurred on this transaction because you have given the customer a refund. z other: A reversal has occurred on this transaction due to a reason not listed above. INVNUM Invoice number you set in the original transaction. Character length and limitations: 127 single-byte alphanumeric characters CUSTOM Custom field you set in the original transaction. Character length and limitations: 127 single-byte alphanumeric characters NOTE Memo entered by your customer in PayPal Website Payments note field. Character length and limitations: 255 single-byte alphanumeric characters SALESTAX Amount of tax charged on payment April 2007 Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference GetTransactionDetails TABLE A.15 GetTransactionDetails Response Fields (Continued) Parameter Description L_DESCn Item name set by you or entered by the customer. If this was a shopping cart transaction, PayPal appends the number of the item to the HTML item_name variable. For example, item_name1, item_name2, and so forth. Character length and limitations: 127 single-byte alphanumeric characters These parameters should be ordered sequentially beginning with 0, for example, L_DESC0, L_DESC1, and so forth. L_NUMBERn Item number set by you. If this was a shopping cart transaction, PayPal appends the number of the item to the HTML item_number variable. For example, item_number1, item_number2, and so forth. Character length and limitations: 127 single-byte alphanumeric characters These parameters should be ordered sequentially beginning with 0, for example, L_NUMBER0, L_NUMBER1, and so forth. L_QTYn Quantity set by you or entered by the customer. Character length and limitations: no limit These parameters should be ordered sequentially beginning with 0, for example, L_QTY0, L_QTY1, and so forth. L_AMTn Cost of item These parameters should be ordered sequentially beginning with 0, for example, L_AMT0, L_AMT1, and so forth. L_OPTIONSn PayPal item options for shopping cart These parameters should be ordered sequentially beginning with 0, for example, L_OPTIONS0, L_OPTIONS1, and so forth. SUBSCRIPTIONID ID generated by PayPal for the subscriber. Character length and limitations: no limit SUBSCRIPTIONDATE Subscription start date EFFECTIVEDATE Date when the subscription modification will be effective RETRYTIME Date PayPal will retry a failed subscription payment. USERNAME Username generated by PayPal and given to subscriber to access the subscription. Character length and limitations: 64 alphanumeric single-byte characters PASSWORD Password generated by PayPal and given to subscriber to access the subscription. For security, the value of the password is hashed. Character length and limitations: 128 alphanumeric single-byte characters RECURRENCES The number of payment installments that will occur at the regular rate. Character length and limitations: no limit REATTEMPT Indicates whether reattempts should occur upon payment failures Name-Value Pair API Developer Guide and Reference April 2007 59 NVP API Method and Field Reference Mass Payment TABLE A.15 GetTransactionDetails Response Fields (Continued) Parameter Description RECURRING Indicates whether regular rate recurs. 1 = Yes PERIOD The period of time that the subscriber will be charged. Character length and limitations: no limit BUYERID Customer’s auction ID CLOSINGDATE Auction’s close date MULTIITEM Counter used for multi-item auction payments Mass Payment TABLE A.16 MassPay Parameters Parameter Description Require d? METHOD Name of the API: MassPay Yes RECEIVERTYPE Indicates how you identify the recipients of payments in all the individual mass payment items: either by EmailAddress (L_EMAILn in the individual item) or by UserID (L_RECEIVERID_n in the individual item). Yes L_AMTn Payment amount. Yes CURRENCYCODE A three-character currency code for one of the currencies listed in PayPaySupported Transactional Currencies. Default: USD. Yes L_EMAILn Email address of recipient. Depends on RECEIVE RTYPE N O T E : You must specify either L_EMAILn or L_RECEIVERIDn, but you must not mix them. Use only one or the other, but not both, in a single request. Character length and limitations: 127 single-byte characters maximum. These parameters should be ordered sequentially beginning with 0, for example, L_EMAIL0, L_EMAIL1, and so forth. L_RECEIVERIDn Unique PayPal customer account number. This value corresponds to the value of PAYERID returned by GetTransactionDetails. These parameters should be ordered sequentially beginning with 0, for example, L_RECEIVERID0, L_RECEIVERID1, and so forth. 60 April 2007 Depends on RECEIVE RTYPE Name-Value Pair API Developer Guide and Reference NVP API Method and Field Reference Mass Payment TABLE A.16 MassPay Parameters (Continued) Require d? Parameter Description L_UNIQUEIDn Transaction-specific identification number for tracking in an accounting system. Character length and limitations: 30 single-byte characters. No whitespace allowed. No These parameters should be ordered sequentially beginning with 0, for example, L_UNIQUEID0, L_UNIQUEID1, and so forth. L_NOTEn Custom note for each recipient. Character length and limitations: 4,000 single-byte alphanumeric characters No These parameters should be ordered sequentially beginning with 0, for example, L_NOTE0, L_NOTE1, and so forth. EMAILSUBJECT The subject line of the email that PayPal sends when the transaction is completed. The subject line is the same for all recipients. Character length and limitations: 255 single-byte alphanumeric characters No TABLE A.17 MassPay Response Fields The fields in the response are the standard response header fields. See [successResponseHeader]. Name-Value Pair API Developer Guide and Reference April 2007 61 NVP API Method and Field Reference Mass Payment 62 April 2007 Name-Value Pair API Developer Guide and Reference B Error Message Reference This chapter contains error messages for the API. Error Response Format If the ACK value is Error or Warning, specific API response fields are not returned. An error response has the following general format TABLE B.1 Response Fields on Error Format of an Error Response ACK=Error&TIMESTAMP=date/timeOfResponse &CORRELATIONID=debuggingToken&VERSION=2.300000 &BUILD=buildNumber&L_ERRORCODE0=errorCode& L_SHORTMESSAGE0=shortMessage &L_LONGMESSAGE0=longMessage&L_SEVERITYCODE0=severityCode Multiple errors can be returned. Each set of errors has a different numeric suffix, starting with 0 and incremented by one for each error. Validation Errors TABLE B.1 Validation Errors Error Code Short Message Long Message 81000 Missing Parameter Required Parameter Missing : Unable to identify parameter 81001 Invalid Parameter A Parameter is Invalid : Unable to identify parameter 81002 Unspecified Method Method Specified is not Supported 81003 Unspecified Method No Method Specified 81004 Unspecified Method No Request Received 81100 Missing Parameter OrderTotal (Amt) : Required parameter missing 81101 Missing Parameter MaxAmt : Required parameter missing 81102 Missing Parameter ReturnURL: Required parameter missing 81103 Missing Parameter NotifyURL : Required parameter missing 81104 Missing Parameter CancelURL : Required parameter missing Name-Value Pair API Developer Guide and Reference March 2007 63 Error Message Reference Validation Errors TABLE B.1 Validation Errors 64 Error Code Short Message Long Message 81105 Missing Parameter ShipToStreet : Required parameter missing 81106 Missing Parameter ShipToStreet2 : Required parameter missing 81107 Missing Parameter ShipToCity : Required parameter missing 81108 Missing Parameter ShipToState : Required parameter missing 81109 Missing Parameter ShipToZip : Required parameter missing 81110 Missing Parameter Country : Required parameter missing 81111 Missing Parameter ReqConfirmShipping : Required parameter missing 81112 Missing Parameter NoShipping : Required parameter missing 81113 Missing Parameter AddrOverride : Required parameter missing 81114 Missing Parameter LocaleCode : Required parameter missing 81115 Missing Parameter PaymentAction : Required parameter missing 81116 Missing Parameter Email : Required parameter missing 81117 Missing Parameter Token : Required parameter missing 81118 Missing Parameter PayerID : Required parameter missing 81119 Missing Parameter ItemAmt : Required parameter missing 81120 Missing Parameter ShippingAmt : Required parameter missing 81121 Missing Parameter HandlingTotal Amt : Required parameter missing 81122 Missing Parameter TaxAmt : Required parameter missing 81123 Missing Parameter IPAddress : Required parameter missing 81124 Missing Parameter ShipToName : Required parameter missing 81125 Missing Parameter L_Amt : Required parameter missing 81126 Missing Parameter Amt : Required parameter missing 81127 Missing Parameter L_TaxAmt : Required parameter missing 81128 Missing Parameter AuthorizationID : Required parameter missing 81129 Missing Parameter CompleteType : Required parameter missing 81130 Missing Parameter CurrencyCode : Required parameter missing 81131 Missing Parameter TransactionID : Required parameter missing 81132 Missing Parameter TransactionEntity : Required parameter missing 81133 Missing Parameter Acct : Required parameter missing 81134 Missing Parameter ExpDate : Required parameter missing March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference Validation Errors TABLE B.1 Validation Errors Error Code Short Message Long Message 81135 Missing Parameter FirstName : Required parameter missing 81136 Missing Parameter LastName : Required parameter missing 81137 Missing Parameter Street : Required parameter missing 81138 Missing Parameter Street2 : Required parameter missing 81139 Missing Parameter City : Required parameter missing 81140 Missing Parameter State : Required parameter missing 81141 Missing Parameter Zip : Required parameter missing 81142 Missing Parameter CountryCode : Required parameter missing 81143 Missing Parameter RefundType : Required parameter missing 81144 Missing Parameter StartDate : Required parameter missing 81145 Missing Parameter EndDate : Required parameter missing 81146 Missing Parameter MPID : Required parameter missing 81147 Missing Parameter CreditCardType : Required parameter missing 81148 Missing Parameter User : Required parameter missing 81149 Missing Parameter Pwd : Required parameter missing 81150 Missing Parameter Version : Required parameter missing 81200 Invalid Parameter Amt : Invalid parameter 81201 Invalid Parameter MaxAmt : Invalid parameter 81203 Invalid Parameter NotifyURL : Invalid parameter 81205 Invalid Parameter ShipToStreet : Invalid parameter 81206 Invalid Parameter ShipToStreet2 : Invalid parameter 81207 Invalid Parameter ShipToCity : Invalid parameter 81208 Invalid Parameter ShipToState : Invalid parameter 81209 Invalid Parameter ShipToZip : Invalid parameter 81210 Invalid Parameter Country : Invalid parameter 81211 Invalid Parameter ReqConfirmShipping : Invalid parameter 81212 Invalid Parameter Noshipping : Invalid parameter 81213 Invalid Parameter AddrOverride : Invalid parameter 81214 Invalid Parameter LocaleCode : Invalid parameter 81215 Invalid Parameter PaymentAction : Invalid parameter Name-Value Pair API Developer Guide and Reference March 2007 65 Error Message Reference Validation Errors TABLE B.1 Validation Errors 66 Error Code Short Message Long Message 81219 Invalid Parameter ItemAmt : Invalid parameter 81220 Invalid Parameter ShippingAmt : Invalid parameter 81221 Invalid Parameter HandlingTotal Amt : Invalid parameter 81222 Invalid Parameter TaxAmt : Invalid parameter 81223 Invalid Parameter IPAddress : Invalid parameter 81224 Invalid Parameter ShipToName : Invalid parameter 81225 Invalid Parameter L_Amt : Invalid parameter 81226 Invalid Parameter Amt : Invalid parameter 81227 Invalid Parameter L_TaxAmt : Invalid parameter 81229 Invalid Parameter CompleteType : Invalid parameter 81230 Invalid Parameter CurrencyCode : Invalid parameter 81232 Invalid Parameter TransactionEntity : Invalid parameter 81234 Invalid Parameter ExpDate : Invalid parameter 81235 Invalid Parameter FirstName : Invalid parameter 81236 Invalid Parameter LastName : Invalid parameter 81237 Invalid Parameter Street : Invalid parameter 81238 Invalid Parameter Street2 : Invalid parameter 81239 Invalid Parameter City : Invalid parameter 81243 Invalid Parameter RefundType : Invalid parameter 81244 Invalid Parameter StartDate : Invalid parameter 81245 Invalid Parameter EndDate : Invalid parameter 81247 Invalid Parameter CreditCardType : Invalid parameter 81248 Invalid Parameter Username : Invalid parameter 81249 Invalid Parameter Password : Invalid parameter 81250 Invalid Parameter Version : Invalid parameter 81251 Internal Error Internal Service Error March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference General API Errors General API Errors TABLE B.2 General API Errors Error Code Short Message Long Message Correcting This Error This error can be caused by an incorrect API username, an incorrect API password, or an invalid API signature. Make sure that all three of these values are correct. For your security, PayPal does not report exactly which of these three values might be in error. 10002 Authentication /Authorization Failed Username/Password is incorrect 10002 Authentication /Authorization Failed You do not have permissions to make this API call 10002 Authentication /Authorization Failed Account is locked or inactive 10002 Internal Error Internal Error 10002 Authentication /Authorization Failed Internal Error 10002 Authentication /Authorization Failed Account is not verified 10002 Authentication /Authorization Failed This call is not defined in the database! 10002 Authentication /Authorization Failed Token is not valid 10002 Restricted account Account is restricted Name-Value Pair API Developer Guide and Reference March 2007 Your PayPal merchant account has been restricted. Contact your PayPal account manager for resolution. 67 Error Message Reference Express Checkout API Errors TABLE B.2 General API Errors Error Code Short Message Long Message Correcting This Error 10002 Authentication /Authorization Failed Token is not valid 10002 Authentication /Authorization Failed API access is disabled for this account 10002 Authentication /Authorization Failed Client certificate is disabled 10002 Restricted account Account is restricted Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code 68 Short Message Long Message Correcting This Error... 10001 ButtonSource value truncated. The transaction could not be loaded 10001 Internal Error Internal Error 10004 Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. 10004 Transaction refused because of an invalid argument. See additional error messages for details. The transaction id is not valid March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Short Message Long Message 10007 Permission denied You do not have permissions to make this API call 10102 PaymentActio n of Order Temporarily Unavailable PaymentAction of Order is temporarily unavailable. Please try later or use other PaymentAction. 10103 Please use another Solution Type. Your Solution Type is temporarily unavailable. If possible, please use another Solution Type. 10402 Authorization only is not allowed for merchant. This merchant account is not permitted to set PaymentAction to Authorization. Please contact Customer Service. 10404 Transaction refused because of an invalid argument. See additional error messages for details. ReturnURL is missing. 10405 Transaction refused because of an invalid argument. See additional error messages for details. CancelURL is missing. 10407 Transaction refused because of an invalid argument. See additional error messages for details. Invalid buyer email address (BuyerEmail). 10409 You're not authorized to access this info. Express Checkout token was issued for a merchant account other than yours. Error Code Name-Value Pair API Developer Guide and Reference March 2007 Correcting This Error... 69 Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors 70 Error Code Short Message Long Message 10410 Invalid token Invalid token. 10411 This Express Checkout session has expired. This Express Checkout session has expired. Token value is no longer valid. March 2007 Correcting This Error... The token returned by SetExpressCheckout response expires after three hours. If you attempt to send the DoExpressCheckoutPaym ent after that time, you will receive error code 10411 in the DoExpressCheckoutPaym ent response. If you receive this error, you must return your customer to PayPal to approve the use of PayPal again. Display an error message to inform the customer that the transaction expired, and provide a button to return to PayPal. In this situation, you are effectively restarting the entire checkout process. (Do not reuse the expired token value on SetExpressCheckout request.) However, because you already know the final OrderTotal, be sure to update the value for that element if appropriate. You might also want to update the values for ReturnURL and CancelURL, if necessary. Name-Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Short Message Long Message Correcting This Error... 10412 Duplicate invoice Payment has already been made for this InvoiceID. PayPal checks that InvoiceID values are unique for any particular merchant. If you send an InvoiceID value already associated with another transaction in the PayPal system, PayPal returns error code 10412. You might not be able to correct this error during an actual checkout. If you get this error, research why might occur and modify your implementation of Express Checkout to ensure that you generate unique invoice identification numbers. 10415 Transaction refused because of an invalid argument. See additional error messages for details. A successful transaction has already been completed for this token. PayPal allows a token only once for a successful transaction. Handling this error If you determine that your customers are clicking your “Place Order” button twice, PayPal recommends that you disable the button after your customer has clicked it. 10425 Express Checkout has been disabled for this merchant. Express Checkout has been disabled for this merchant. Please contact Customer Service. 10432 Transaction refused because of an invalid argument. See additional error messages for details. Invoice ID value exceeds maximum allowable length. Error Code Name-Value Pair API Developer Guide and Reference March 2007 71 Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code 72 Short Message Long Message Correcting This Error... 10433 Transaction refused because of an invalid argument. See additional error messages for details. Value of OrderDescription element has been truncated. 10434 Transaction refused because of an invalid argument. See additional error messages for details. Value of Custom element has been truncated. 10436 Transaction refused because of an invalid argument. See additional error messages for details. PageStyle value exceeds maximum allowable length. 10437 Transaction refused because of an invalid argument. See additional error messages for details. cpp-header-image value exceeds maximum allowable length. 10438 Transaction refused because of an invalid argument. See additional error messages for details. cpp-header-image value exceeds maximum allowable length. March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code Short Message Long Message 10439 Transaction refused because of an invalid argument. See additional error messages for details. cpp-header-image value exceeds maximum allowable length. 10440 Transaction refused because of an invalid argument. See additional error messages for details. cpp-header-image value exceeds maximum allowable length. 10471 Transaction refused because of an invalid argument. See additional error messages for details. ReturnURL: Invalid parameter 10472 Transaction refused because of an invalid argument. See additional error messages for details. CancelURL is invalid. 10537 Risk Control Country Filter Failure The transaction was refused because the country was prohibited as a result of your Country Monitor Risk Control Settings. 10538 Risk Control Max Amount Failure The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk Control Settings. Name-Value Pair API Developer Guide and Reference March 2007 Correcting This Error... 73 Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code Short Message Long Message Correcting This Error... 10539 Payment declined by your Risk Controls settings: PayPal Risk Model. Payment declined by your Risk Controls settings: PayPal Risk Model. 10725 Shipping Address Country Error There was an error in the Shipping Address Country field 10727 Shipping Address1 Empty The field Shipping Address1 is required 10728 Shipping Address City Empty The field Shipping Address City is required 10729 Shipping Address State Empty The field Shipping Address State is required 10730 Shipping Address Postal Code Empty The field Shipping Address Postal Code is required 10731 Shipping Address Country Empty The field Shipping Address Country is required 10736 Shipping Address Invalid City State Postal Code A match of the Shipping Address City, State, and Postal Code failed. TABLE B.4 GetExpressCheckoutDetails API Errors 74 Error Code Short Message Long Message 10001 Internal Error Internal Error 10001 Internal Error Transaction failed due to internal error Correcting This Error... March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B.4 GetExpressCheckoutDetails API Errors Error Code Short Message 10001 ButtonSource value truncated. The transaction could not be loaded 10001 ButtonSource value truncated. The transaction could not be loaded 10004 Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. 10004 Transaction refused because of an invalid argument. See additional error messages for details. The transaction id is not valid 10004 Invalid transaction type You can not get the details for this type of transaction 10004 Transaction refused because of an invalid argument. See additional error messages for details. The transaction could not be loaded 10004 Transaction refused because of an invalid argument. See additional error messages for details. The transaction id is not valid Long Message Name-Value Pair API Developer Guide and Reference Correcting This Error... March 2007 75 Error Message Reference Express Checkout API Errors TABLE B.4 GetExpressCheckoutDetails API Errors Error Code Short Message Long Message 10007 Permission denied You do not have permissions to make this API call 10007 Permission denied You do not have permission to get the details of this transaction 10007 Permission denied You do not have permissions to make this API call 10408 Express Checkout token is missing. Express Checkout token is missing. 10409 You're not authorized to access this info. Express Checkout token was issued for a merchant account other than yours. 10410 Invalid token Invalid token. 10411 This Express Checkout session has expired. This Express Checkout session has expired. Token value is no longer valid. Correcting This Error... TABLE B.5 DoExpressCheckoutPayment API Errors 76 Error Code Short Message 10001 Internal Error Transaction failed due to internal error 10001 Internal Error Warning an internal error has occurred. The transaction id may not be correct 10001 ButtonSource value truncated. The transaction could not be loaded 10001 Internal Error Internal Error Long Message Correcting This Error... March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code Short Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. 10004 Transaction refused because of an invalid argument. See additional error messages for details. The transaction id is not valid 10007 Permission denied You do not have permissions to make this API call 10406 Transaction refused because of an invalid argument. See additional error messages for details. The PayerID value is invalid. 10408 Express Checkout token is missing. Express Checkout token is missing. 10409 You're not authorized to access this info. Express Checkout token was issued for a merchant account other than yours. 10410 Invalid token Invalid token. 10411 This Express Checkout session has expired. This Express Checkout session has expired. Token value is no longer valid. 10412 Duplicate invoice Payment has already been made for this InvoiceID. Long Message Name-Value Pair API Developer Guide and Reference Correcting This Error... March 2007 77 Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors 78 Error Code Short Message 10413 Long Message Correcting This Error... Transaction refused because of an invalid argument. See additional error messages for details. The totals of the cart item amounts do not match order amounts. If you include any of the following element values with DoExpressCheckoutPayment, the sum of their values must equal the value of OrderTotal. z ItemTotal z ShippingTotal z HandlingTotal z TaxTotal If you get this error, research why it might have occurred and modify your implementation of Express Checkout to ensure proper addition of the values. 10414 Transaction refused because of an invalid argument. See additional error messages for details. The amount exceeds the maximum amount for a single transaction. 10415 Transaction refused because of an invalid argument. See additional error messages for details. A successful transaction has already been completed for this token. 10416 Transaction refused because of an invalid argument. See additional error messages for details. You have exceeded the maximum number of payment attempts for this token. You can send a maximum of 10 DoExpressCheckoutPayment API calls for any single token value, after which the token becomes invalid. March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code Short Message 10417 Long Message Correcting This Error... Transaction cannot complete. The transaction cannot complete successfully. Instruct the customer to use an alternative payment method. It is possible that the payment method the customer chooses on PayPal might not succeed when you send DoExpressCheckoutPayment. The most likely cause is that the customer’s credit card failed bank authorization. Another possible, though rare, cause is that the final OrderTotal is significantly higher than the original estimated OrderTotal you sent with SetExpressCheckout at Integration Point 1, and the final OrderTotal does not pass PayPal’s risk model analysis. If the customer has no other PayPal funding source that is likely to succeed, DoExpressCheckoutPayment response returns error code 10417. Instruct the customer that PayPal is unable to process the payment and redisplay alternative payment methods with which the customer can pay. 10418 Transaction refused because of an invalid argument. See additional error messages for details. The currencies of the shopping cart amounts must be the same. 10419 Express Checkout PayerID is missing. Express Checkout PayerID is missing. 10420 Transaction refused because of an invalid argument. See additional error messages for details. Express Checkout PaymentAction is missing. Name-Value Pair API Developer Guide and Reference March 2007 79 Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors 80 Error Code Short Message 10421 Long Message Correcting This Error... This Express Checkout session belongs to a different customer. This Express Checkout session belongs to a different customer. Token value mismatch. When your customer logs into PayPal, the PayPal PayerID is associated with the Express Checkout token. This error is caused by mixing tokens for two different PayerIDs. The Token and PayerID returned for any particular customer by GetExpressCheckoutDetails response must be the same ones you send with DoExpressCheckoutPayment. Verify that your programs are properly associating the Tokens and PayerIDs. 10422 Customer must choose new funding sources. The customer must return to PayPal to select new funding sources. It is possible that the payment method the customer chooses on PayPal might not succeed when you send DoExpressCheckoutPayment request. If the customer has a different PayPal funding source that is likely to succeed, DoExpressCheckoutPayment response returns error code 10422 so you can redirect the customer back to PayPal. 10423 Transaction refused because of an invalid argument. See additional error messages for details. This transaction cannot be completed with PaymentAction of Authorization. This error occurs if at Integration Point 1, you set PaymentAction to Sale with SetExpressCheckout request but at Integration Point 3, you set PaymentAction to Authorization with DoExpressCheckoutPayment. PayPal does not allow this switch from Sale to Authorization in a single checkout session. PayPal does allow the reverse, however. You can set PaymentAction to Authorization with SetExpressCheckout at Integration Point 1 and switch PaymentAction to Sale with DoExpressCheckoutPayment at Integration Point 3. 10424 Transaction refused because of an invalid argument. See additional error messages for details. Shipping address is invalid. If you receive this error message, PayPal recommends that you return your customer to PayPal to review and approve new valid funding sources. Although this error is rare, you should consider trapping the error to display a message to the customer describing what happened, along with a button or hyperlink to return to PayPal. For the rules of this calculation, see the chapter about best practices in the PayPal Express Checkout Integration Guide. March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code Short Message 10431 Item amount is invalid. Item amount is invalid. 10432 Transaction refused because of an invalid argument. See additional error messages for details. Invoice ID value exceeds maximum allowable length. 10433 Transaction refused because of an invalid argument. See additional error messages for details. Value of OrderDescription element has been truncated. 10434 Transaction refused because of an invalid argument. See additional error messages for details. Value of Custom element has been truncated. 10435 Transaction refused because of an invalid argument. See additional error messages for details. The customer has not yet confirmed payment for this Express Checkout session. 10441 Transaction refused because of an invalid argument. See additional error messages for details. The NotifyURL element value exceeds maximum allowable length. Long Message Name-Value Pair API Developer Guide and Reference Correcting This Error... March 2007 81 Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors 82 Error Code Short Message Long Message 10442 ButtonSource value truncated. The ButtonSource element value exceeds maximum allowable length. 10443 Transaction refused because of an invalid argument. See additional error messages for details. This transaction cannot be completed with PaymentAction of Order. 10444 Transaction refused because of an invalid argument. See additional error messages for details. The transaction currency specified must be the same as previously specified. 10445 This transaction cannot be processed at this time. Please try again later. This transaction cannot be processed at this time. Please try again later. 10446 Unconfirmed email A confirmed email is required to make this API call. 10474 Invalid Data This transaction cannot be processed. The country code in the shipping address must match the buyer’s country of residence. 10537 Risk Control Country Filter Failure The transaction was refused because the country was prohibited as a result of your Country Monitor Risk Control Settings. 10538 Risk Control Max Amount Failure The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk Control Settings. Correcting This Error... The buyer selects the country of residence when they sign up for their PayPal account. The country of residence is displayed after the dash in the title on the Account Overview page. March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code Short Message 10539 Payment declined by your Risk Controls settings: PayPal Risk Model. Payment declined by your Risk Controls settings: PayPal Risk Model. 10725 Shipping Address Country Error There was an error in the Shipping Address Country field 10727 Shipping Address1 Empty The field Shipping Address1 is required 10728 Shipping Address City Empty The field Shipping Address City is required 10729 Shipping Address State Empty The field Shipping Address State is required 10730 Shipping Address Postal Code Empty The field Shipping Address Postal Code is required 10731 Shipping Address Country Empty The field Shipping Address Country is required 10736 Shipping Address Invalid City State Postal Code A match of the Shipping Address City, State, and Postal Code failed. Long Message Name-Value Pair API Developer Guide and Reference Correcting This Error... March 2007 83 Error Message Reference RefundTransaction API Errors RefundTransaction API Errors TABLE B.6 RefundTransaction API Errors 84 Error Code Short Message Long Message 10001 Internal Error Internal Error 10001 Internal Error Warning an internal error has occurred. The transaction id may not be correct 10001 ButtonSource value truncated. The transaction could not be loaded 10001 Internal Error Internal Error 10004 Transaction refused because of an invalid argument. See additional error messages for details. The partial refund amount must be a positive amount 10004 Transaction refused because of an invalid argument. See additional error messages for details. You can not specify a partial amount with a full refund 10004 Transaction refused because of an invalid argument. See additional error messages for details. A transaction id is required March 2007 Correcting This Error... Name-Value Pair API Developer Guide and Reference Error Message Reference RefundTransaction API Errors TABLE B.6 RefundTransaction API Errors Error Code Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. The partial refund amount must be a positive amount 10004 Transaction refused because of an invalid argument. See additional error messages for details. You can not specify a partial amount with a full refund 10004 Transaction refused because of an invalid argument. See additional error messages for details. A transaction id is required 10004 Transaction refused because of an invalid argument. See additional error messages for details. Transaction class is not supported 10004 Transaction refused because of an invalid argument. See additional error messages for details. The transaction id is not valid 10007 Permission denied You do not have permission to refund this transaction Name-Value Pair API Developer Guide and Reference March 2007 Correcting This Error... 85 Error Message Reference RefundTransaction API Errors TABLE B.6 RefundTransaction API Errors Short Message Long Message 10007 Permission denied You do not have permissions to make this API call 10009 Transaction refused You do not have a verified ACH 10009 Transaction refused The partial refund amount must be less than or equal to the original transaction amount 10009 Transaction refused The partial refund amount must be less than or equal to the remaining amount 10009 Transaction refused The partial refund amount is not valid 10009 Transaction refused Because a complaint case exists on this transaction, only a refund of the full or full remaining amount of the transaction can be issued 10009 Transaction refused You are over the time limit to perform a refund on this transaction 10009 Transaction refused Can not do a full refund after a partial refund 10009 Transaction refused Account is locked or inactive 10009 Transaction refused The partial refund must be the same currency as the original transaction 10009 Transaction refused This transaction has already been fully refunded Error Code 86 March 2007 Correcting This Error... This error can be caused by insufficient funds in your PayPal balance to cover the amount of the refund and either your not having yet verified the bank account associated with your PayPal account or your not having any bank account associated with your PayPal account at all. Ensure that you have sufficient funds in your PayPal balance and that you have verified the associated bank account. Name-Value Pair API Developer Guide and Reference Error Message Reference TransactionSearch API Errors TABLE B.6 RefundTransaction API Errors Error Code Short Message Long Message 10009 Transaction refused Account is restricted 10009 Transaction refused You can not refund this type of transaction 10009 Transaction refused You can not do a partial refund on this transaction 10009 Transaction refused The account for the counterparty is locked or inactive 10009 Transaction refused You can not refund this type of transaction 10011 Invalid transaction id value Transaction refused because of an invalid transaction id value 11001 Transaction refused because of an invalid argument. See additional error messages for details. Transaction class is not supported Correcting This Error... TransactionSearch API Errors TABLE B.2 TransactionSearch API Errors Error Code Short Message Long Message 10001 Internal Error Internal Error 10001 ButtonSource value truncated. The transaction could not be loaded 10003 Transaction refused because of an invalid argument. See additional error messages for details. Start date is a required parameter Name-Value Pair API Developer Guide and Reference March 2007 87 Error Message Reference TransactionSearch API Errors TABLE B.2 Error Code 88 TransactionSearch API Errors Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. Start date is invalid 10004 Transaction refused because of an invalid argument. See additional error messages for details. End date is invalid 10004 Transaction refused because of an invalid argument. See additional error messages for details. Currency is not supported 10004 Transaction refused because of an invalid argument. See additional error messages for details. Transaction class is not supported 10004 Transaction refused because of an invalid argument. See additional error messages for details. Receipt id is not valid 10004 Transaction refused because of an invalid argument. See additional error messages for details. Payer email is invalid 10004 Transaction refused because of an invalid argument. See additional error messages for details. Auction item id is not valid 10004 Transaction refused because of an invalid argument. See additional error messages for details. Receiver email is invalid 10004 Transaction refused because of an invalid argument. See additional error messages for details. You can not search for a transaction id and a receipt id 10004 Transaction refused because of an invalid argument. See additional error messages for details. Receiver can only be specified for payments you've received March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference GetTransactionDetails API Errors TABLE B.2 Error Code TransactionSearch API Errors Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. The transaction id is not valid 10007 Permission denied You do not have permissions to search for this transaction 10007 Permission denied You do not have permissions to make this API call 11002 Search warning The number of results were truncated. Please change your search parameters if you wish to see all your results. GetTransactionDetails API Errors TABLE B.7 GetTransactionDetails API Errors Error Code Short Message Long Message 10001 Internal Error Internal Error MassPay API Errors TABLE B.8 MassPay API Errors Short Message Long Message 10001 Invalid account number. The transaction failed as a result of an invalid credit card number. Check the number or attempt with another card. 10001 Internal Error Internal Error 10001 Internal Error The transaction could not be loaded 10001 ButtonSource value truncated. The transaction could not be loaded Error Code Name-Value Pair API Developer Guide and Reference March 2007 89 Error Message Reference MassPay API Errors TABLE B.8 MassPay API Errors Error Code 90 Short Message Long Message 10001 Transaction refused because of an invalid argument. See additional error messages for details. The masspay receiver_type is not a recognizable type 10002 Account locked The user account is locked 10004 Transaction refused because of an invalid argument. See additional error messages for details. The number of input records is greater than maximum allowed 10004 Transaction refused because of an invalid argument. See additional error messages for details. The number of input records is less than or equal to zero 10004 Transaction refused because of an invalid argument. See additional error messages for details. The note string length exceeds the maximum limit of 4000 characters 10004 Transaction refused because of an invalid argument. See additional error messages for details. The amount is missing March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference MassPay API Errors TABLE B.8 MassPay API Errors Error Code Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. The currency is missing 10004 Transaction refused because of an invalid argument. See additional error messages for details. Currency is not supported 10004 Transaction refused because of an invalid argument. See additional error messages for details. The amount is not a valid number 10004 Transaction refused because of an invalid argument. See additional error messages for details. The amount exceeds the max limit of a single mass pay item ~1 10004 Transaction refused because of an invalid argument. See additional error messages for details. The amount is less than or equal to zero Name-Value Pair API Developer Guide and Reference March 2007 91 Error Message Reference MassPay API Errors TABLE B.8 MassPay API Errors Error Code 92 Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. The unique id string length exceeds the maximum limit of 30 characters 10004 Transaction refused because of an invalid argument. See additional error messages for details. The unique id string contains a space as a character 10004 Transaction refused because of an invalid argument. See additional error messages for details. The transaction id is not valid 10007 Permission denied You do not have permissions to make this API call 10301 User not allowed The user is not allowed to send money through Mass Pay 10303 Restricted account Account is restricted 10304 Unconfirmed email The user account has unconfirmed email 10305 Limit Exceeded The user account needs to have its sending limit removed in order to make a mass payment. 10306 Limit Exceeded The user’s international account needs to have its sending limit removed in order to make a mass payment 10307 Receive only account The user account is receive only and therefore cannot send payments out March 2007 Name-Value Pair API Developer Guide and Reference Error Message Reference MassPay API Errors TABLE B.8 MassPay API Errors Error Code Short Message Long Message 10308 Masspay server configuration error There is some configuration error 10309 Masspay server unavailable The mass pay server is unavailable 10310 Unable to create payment Unable to create payments for masspay 10311 Unable to submit payment Unable to submit payments for masspay 10312 Masspay server error The masspay server has reported errors 10313 Masspay Invalid Data The masspay input file includes invalid data 10314 Masspay input parse error The input to the masspay server is incorrect. Please make sure that you are using a correctly formatted input. 10317 Masspay Invalid Email The masspay input file includes invalid Email 10320 Internal Error Internal Error 10321 Insufficient funds The account does not have sufficient funds to do this masspay 10327 Masspay Invalid UserID The masspay input file includes invalid UserID Name-Value Pair API Developer Guide and Reference March 2007 93 Error Message Reference MassPay API Errors 94 March 2007 Name-Value Pair API Developer Guide and Reference C NVP API Web Samples This chapter describes the NVP API Web Samples which access the NVP API directly. This section includes the following topics: z “Descriptions of the Samples” on page 95 z “Samples Using PHP” on page 99 z “Samples Using PHP” on page 99 z “Samples Using Classic ASP” on page 100 Descriptions of the Samples The web samples consist of the following: z “Accepting PayPal in Express Checkout” on page 95 z “Getting Transaction Details” on page 97 z “Common Files” on page 98 The main page of the samples, index.html or Default.htm, contains links to each sample. N O T E : We describe the code samples for all programming languages in this section. Language specific filenames are shown as filename.ext. For example, SetExpressCheckout.ext stands for SetExpressCheckout.java, SetExpressCheckout.php, and so forth. Accepting PayPal in Express Checkout This sample shows how to use Express Checkout to accept payments using PayPal. Access this sample from the following choices displayed on index.html or Default.htm: ExpressCheckout - Sale Name-Value Pair API Developer Guide and Reference Do basic checkout with PayPal. In the SetExpressCheckout request, the PAYMENTACTION parameter is set to Sale. April 2007 95 NVP API Web Samples Descriptions of the Samples The primary files for this sample are: TABLE C.1 Express Checkout Files File Description SetExpressCheckout.ext This is the main web page for the Express Checkout sample. The page allows the user to enter amount and currency type. It also accept input variable paymentType which becomes the value of the PAYMENTACTION parameter. When the user clicks the Submit button, ReviewOrder.ext is called. Called by index.html or Default.htm. Calls ReviewOrder.ext. ReviewOrder.ext This file is called after the user clicks on a button during the checkout process to use PayPal's Express Checkout. The user logs in to their PayPal account. This file is called twice. On the first pass, the code executes the if statement: if (! isset ($token)) The code collects transaction parameters from the form displayed by SetExpressCheckout.ext then constructs and sends a SetExpressCheckout request string to the PayPal server. The paymentType variable becomes the PAYMENTACTION parameter of the request string. The RETURNURL parameter is set to this file; this is how ReviewOrder.ext is called twice. On the second pass, the code executes the else statement. On the first pass, the buyer completed the authorization in their PayPal account; now the code gets the payer details by sending a GetExpressCheckoutDetails request to the PayPal server. Then the code calls GetExpressCheckoutDetails.ext. N O T E : Be sure to check the value of PAYPAL_URL. The buyer is sent to this URL to authorize payment with their PayPal account. For testing purposes, this should be set to the PayPal sandbox. Called by SetExpressCheckout.ext. Calls GetExpressCheckoutDetails.ext, CallerService.ext, and Display.ext. GetExpressCheckoutDetails.ext 96 This functionality is called after the buyer returns from PayPal and has authorized the payment. Displays the payer details returned by the GetExpressCheckoutDetails response and calls DoExpressCheckoutPayment.ext to complete the payment authorization. Called by ReviewOrder.ext. Calls DoExpressCheckoutPayment.ext and CallerService.ext. April 2007 Name-Value Pair API Developer Guide and Reference NVP API Web Samples Descriptions of the Samples TABLE C.1 Express Checkout Files (Continued) File Description DoExpressCheckoutPayment.ext This functionality is called to complete the payment with PayPal and display the result to the buyer. The code constructs and sends the DoExpressCheckoutPayment request string to the PayPal server. Called by GetExpressCheckoutDetails.ext and CallerService.ext. Getting Transaction Details This sample shows how to use the GetTransactionDetails request. Access this sample from the following choice displayed on index.html or Default.htm: GetTransactionDetails Gets transaction details for a specific transaction ID. The main page displays a text box where the user enters a transaction ID. When the user clicks the Submit button, the code constructs an NVP API request to GetTransactionDetails and sends it to the PayPal server. The primary files for this sample are: TABLE C.2 Get Transaction Details Files File Description GetTransactionDetails.ext This is the main page for GetTransactionDetails sample. This page displays a text box where the user enters a transaction ID and a Submit button that calls TransactionDetails.ext. Calls TransactionDetails.ext. TransactionDetails.ext Sends a GetTransactionDetails NVP API request to PayPal. The code retrieves the transaction ID and constructs the NVP API request string to send to the PayPal server. The request to PayPal uses an API signature. After receiving the response from the PayPal server, the code displays the request and response in the browser. If the response was a success, it displays the response parameters. If the response was an error, it displays the errors received. Called by GetTransactionDetails.html. Name-Value Pair API Developer Guide and Reference April 2007 97 NVP API Web Samples Common Files The following files are common to the samples. TABLE C.3 Common Files File Description index.html Default.htm The main web page with links to each sample. Calls SetExpressCheckout.ext, and GetTransactionDetails.html. sdk.css Cascading Style Sheet (CSS) used by index.html or Default.htm. CallerService.ext This is the configuration file for the samples.This file contains the parameters needed to make an API call. The samples come with an API signature for making API calls to the PayPal sandbox. The API signature is described in “Sample API User with API Signature” on page 98. Called by TransactionDetails.ext, ReviewOrder.ext, and Display.ext. Display.ext Displays request and response parameters. If there is an error, displays request and error parameters. Called by TransactionDetails.ext, and DoExpressCheckoutPayment.ext. Sample API User with API Signature The samples come with an API signature for use with the samples and the PayPal Sandbox. This API signature belongs to the following user: TABLE C.1 Details of the Sample API Signature API username sdk-three_api1.sdk.com API password QFZCWN5HZM8VBG7Q API signature A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU IMPO RTANT: You must protect the API signature values 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 executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production. 98 April 2007 Name-Value Pair API Developer Guide and Reference NVP API Web Samples Samples Using PHP Samples Using PHP This section contains information for configuring and running the NVP API Web Samples Using PHP. Required Software The following software is required: TABLE C.4 Required Software Software Version Download Location PHP with CURL extension enabled 4.4.2 or greater http://www.php.net/downloads.php Apache HTTP Server 1.3.17 or greater http://httpd.apache.org/ You must install and configure PHP with the Apache HTTP Server. Download and Unzip the Samples The latest version of the Web Samples are available at https://www.paypal.com/IntegrationCenter/ic_nvp.html. 1. Download the zipfile distribution. 2. Unzip the zipfile to any directory of you choose. Installing the Samples Copy the sample folder, php_nvp_samples, to the docroot of the Apache HTTP Server. By default docroot is in datadir/htdocs. Running the Samples First, make sure that you have installed the required software and the samples. You can run the samples by entering the following address in a web browser: http://name_of_Apache_HTTP_Server:port/php_nvp_samples/index.html Name-Value Pair API Developer Guide and Reference April 2007 99 NVP API Web Samples Samples Using Classic ASP Samples Using Classic ASP This section contains information for configuring and running the NVP API Web Samples Using Classic ASP. Required Software No additional software is required. Download and Unzip the Samples The latest version of the Web Samples are available at https://www.paypal.com/IntegrationCenter/ic_nvp.html. 1. Download the zipfile distribution. 2. Unzip the zipfile to any directory of you choose. Installing the Samples The samples must be installed in IIS. The samples require IIS version 5.1 or above. Create a virtual directory named PayPalClassicAspNvpSamples in IIS that points to Samples_Root. Running the Samples First, make sure that you have installed the required software and the samples. You can run the samples by entering the following address in a web browser: http://name_of_Server:port/PayPalClassicAspNvpSamples/Default.htm 100 April 2007 Name-Value Pair API Developer Guide and Reference NVP API Web Samples Samples Using ColdFusion Samples Using ColdFusion This section contains information for configuring and running the NVP API Web Samples Using ColdFusion. Required Software The following software is required: TABLE C.5 Supported Standards Standard Version Download Location ColdFusion 7.x MX http://www.adobe.com/products/coldfusion/ Download and Unzip the Samples The latest version of the Web Samples are available at https://www.paypal.com/IntegrationCenter/ic_nvp.html. 1. Download the zipfile distribution. 2. Unzip the zipfile to any directory of you choose. Installing the Samples N O T E : The samples assume that ColdFusion is running on Microsoft Windows. 3. Copy the sample folder to your ColdFusion application server web document root, ColdFusionMX7_root_directory\wwwroot. Running the Samples First, make sure that you have installed the required software and the samples. You can run the samples by entering the following address in a web browser: http://name_of_Server:port/cf_nvp_samples/index.html Name-Value Pair API Developer Guide and Reference April 2007 101 NVP API Web Samples Samples Using ColdFusion 102 April 2007 Name-Value Pair API Developer Guide and Reference D The Java SDK This section describes how to use the Java SDK for the NVP API and includes the following topics: z “Installing the Java SDK” on page 103 z “Profiles” on page 106 z “Sample Applications” on page 107 Installing the Java SDK This section details the software and hardware supported and required by the PayPal SDK, installation, and post-installation tasks. Supported Standards The PayPal SDK has been verified to work with the following standards. TABLE D.1 Supported Standards Standard Version Java Runtime Environment 1.4.2 or greater Supported Human Languages The PayPal SDK is available in U.S. English. SDK Version Number This guide describes PayPal Java SDK version 5.1.1. Name-Value Pair API Developer Guide and Reference April 2007 103 The Java SDK Installing the Java SDK Recommended Hardware Configuration The minimum hardware requirements for using the PayPal SDK in development and test are listed below. Production systems might require more capacity, depending on their expected load. TABLE D.2 Recommended Hardware Configuration Component Minimum Capacity RAM 256 MB CPU Pentium 1 GHz Disk space 50 MB Download and Unzip the SDK The latest version of the PayPal SDK is available at https://www.paypal.com/IntegrationCenter/ic_nvp.html. 1. Download the zipfile distribution. 2. Unzip the zipfile to any directory of you choose. N O T E : We refer to the directory in which you choose to extract the SDK as: SDK_root. Post-installation Set-up This section details steps you must take before you start using the PayPal SDK. Adding SDK JAR Files to CLASSPATH Before developing applications with the Java SDK, be sure to add the SDK JAR files in SDK_root/lib to your CLASSPATH environment variable. SDK Directories and Optional Configurations The Java SDK components are organized into different subdirectories, as shown in Table D.3, “PayPal SDK for Java: Directories and Contents.” TABLE D.3 104 PayPal SDK for Java: Directories and Contents Directory Descrption cert PayPal public certificates for Live PayPal and PayPal Sandbox docs SDK API documentation lib SDK libraries licenses License files April 2007 Name-Value Pair API Developer Guide and Reference The Java SDK Complete SDK and API Class Documentation TABLE D.3 PayPal SDK for Java: Directories and Contents (Continued) Directory Descrption samples Example code that use the SDK. src SDK source code tools Third-party applications Complete SDK and API Class Documentation Complete Javadoc documentation for all PayPal SDK interfaces, classes, methods, structures, and data types are included with the SDK distribution. To view the documentation, open the following file with your web browser: SDK_root/docs/index.html SDK Logging The PayPal SDK uses log4j public domain logging software. For complete information, see the documentation at http://logging.apache.org/log4j/docs/ Setting Log Levels Set the value of the level element in SDK_root/lib/log4j.properties. TABLE D.4 SDK Logging Levels Level Description ALL Same as DEBUG ERROR Log only severe errors INFO Date/time of API operation, operation name, elapsed time, success or failure indication DEBUG Full text of requests and responses and other debugging messages. Because DEBUG logging can degrade the performance of the SDK, be careful about using it for day-today operation. N O T E : Because requests and responses are asynchronous, the recording of requests and responses might appear out of sequence in the log file. Logfile Backup The default size of the SDK log is 10MB. You can set this size larger or smaller with the value of param name=”MaxFileSize” in log4j.properties. When the log file reaches its maximum size, a backup file is created and a new logfile begins. Name-Value Pair API Developer Guide and Reference April 2007 105 The Java SDK Profiles Profiles Before the SDK can be used, it must know the profile of the user accessing its services. A profile is a collection of information about a merchant or developer who uses the PayPal SDK. An API profile is associated with API Services and includes: z z z z z A PayPal API username and password. If you are using API certificates, the path to the API certificate in P12 format and the private key password to that certificate. If you are using API signatures, the signature string. The optional name of a third-party who authorizes the caller to invoke PayPal APIs on his behalf. This third-party is called a subject The PayPal environment for processing API calls: live or sandbox. An EWP profile is associated with EWP Services includes: z The path to the merchant’s local copy of that public certificate z The private key password for that public certificate z The path to a merchant’s private key file for digitally signing data z The URL to which the button form POSTs z The optional URL of a payment button image. The default is PayPal’s standard Buy Now button. For more information about how EWP works, see the Website Payments Standard Integration Guide, available at https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_IntegrationGuide.pdf. Overview to Profile-related Classes The primary interfaces and classes for SDK profiles are described in Table D.5, “Interface and Classes for SDK Profiles,” on page 106 TABLE D.5 106 Interface and Classes for SDK Profiles Interface/Class Descriptions APIProfile interface This interface defines the basic information that PayPal needs to know about a user of the PayPal Web Service APIs. Developers must create an instance of APIProfile for each account that accesses the APIs. For single-merchant developers, only a single APIProfile instance is needed. PayPal provides two implementation classes suitable for the needs of most SDK developers: CertificateAPIProfile and SignatureAPIProfile. However, you are free to write a custom implementation if you need additional functionality the default classes do not offer. April 2007 Name-Value Pair API Developer Guide and Reference The Java SDK Sample Applications TABLE D.5 Interface and Classes for SDK Profiles (Continued) Interface/Class Descriptions EWPProfile interface This interface defines the basic information that PayPal needs to know about a user of PayPal’s Encrypted Website Payments (EWP) service. Developers must create an instance of EWPProfile for each account that generates the encrypted button code; for single-merchant users this will just be a single instance). PayPal provides a basic implementation class called DefaultEWPProfile suitable for the needs of most SDK developers. However, you are free to write a custom implementation if you need functionality the default class does not offer. ProfileFactory class This class creates both APIProfile and EWPProfile objects. It contains static methods that handle the instantiation and construction of profile objects. Profiles class This data class represents all profiles the SDK knows about. It contains two collections, one for APIProfiles and one for EWPProfiles. This class is provided to ProfileHandler to save profile data and returned from ProfileHandler to retrieve profile data. Sample Application s The PayPal SDK includes sample applications in the SDK_root/samples directory. Each subdirectory comes with a README file that explains how to set up the application. TABLE D.6 PayPal SDK for Java: Sample Code in SDK_root/samples Subdirectory Descrption Cert API certificates used by the sample applications JSP JavaScript implementation for Apache Tomcat of the following PayPal APIs: z Express Checkout for final sale and for authorization z TransactionSearch z GetTransactionDetails z RefundTransaction SampleApp Native Java application to call TransactionSearch, and GetTransactionDetails Name-Value Pair API Developer Guide and Reference April 2007 107 The Java SDK Sample Applications Sample API User with API Signature The samples come with an API signature for use with the samples and the PayPal Sandbox. This API signature belongs to the following user: TABLE D.7 Details of the Sample API Signature API username sdk-three_api1.sdk.com API password QFZCWN5HZM8VBG7Q API signature A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU IMPO RTANT: You must protect the API signature values 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 executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production. Sample API User with API Certificate The samples come with an API digital certificate for use with the SDK and the PayPal Sandbox. This certificate belongs to the following user: TABLE D.8 Details of the SDK Sample API Certificate Location of Certificate SDK_root\samples\Certs\sdk-seller.p12 API Username sdk-seller_api1.sdk.com API Password 12345678 PKCS12 Passphrase password IMPO RTANT: You must protect the API Certificate values 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 executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production. 108 April 2007 Name-Value Pair API Developer Guide and Reference E The ASP.NET SDK This section describes how to use the ASP.NET SDK for the NVP API and includes the following topics: z “Installing the ASP.NET SDK” on page 109 z “Profiles” on page 113 z “Sample Applications” on page 115 Installing the ASP.NET SDK This section details the software and hardware supported and required by the PayPal SDK, installation, and post-installation tasks. Supported Standards The PayPal SDK has been verified to work with the following standards. TABLE E.1 Supported Standards Standard Version Microsoft .NET Framework 1.1, Service Pack 1 Supported Human Languages The PayPal SDK is available in U.S. English. SDK Version Number This guide describes PayPal ASP.NET SDK version 5.1.1. Name-Value Pair API Developer Guide and Reference April 2007 109 The ASP.NET SDK Installing the ASP.NET SDK Minimum Hardware Requirements The following table lists the minimum hardware requirements for using the PayPal SDK in development and test. Production systems might require more capacity, depending on their expected load. TABLE E.2 Minimum System Hardware Requirements Component Minimum Capacity RAM 256 MB CPU Pentium 1 GHz Disk space 50 MB Required: Microsoft .NET Framework 1.1, Service Pack 1 IMPO RTANT: The PayPal SDK requires Service Pack 1 for Microsoft .NET Framework 1.1. You can get Service Pack 1 from the Microsoft web site. Downloading and Installing the SDK The latest version of the PayPal SDK is available at https://www.paypal.com/IntegrationCenter/ic_nvp.html. You can download either a selfextracting installation program or a zipfile distribution. The installation is straightforward and requires no special instruction. You have the option to install the SDK source, if you like. Post-installation Set-up This section details steps to take before you start using the PayPal SDK. Referencing the SDK DLLs Before developing applications with the SDK, be sure to add references in your ASP.NET projects to the SDK dynamic load libraries (DLLs) in SDK_root\bin. Installing the Samples The SDK comes with sample applications for your study and use. These samples can be installed in Microsoft Internet Information Server (IIS). For more information about the samples, see “Sample Applications” on page 115. For more information about installing in IIS, see “Installing the Samples in IIS” on page 116. 110 April 2007 Name-Value Pair API Developer Guide and Reference The ASP.NET SDK Installing the ASP.NET SDK SDK Directories and Optional Configurations The SDK components are organized into different subdirectories, as shown in Table E.3, “PayPal SDK Directories and Contents.” TABLE E.3 PayPal SDK Directories and Contents Directory Descrption bin Compiled SDK DLLs docs Ndoc class documentation and SDK guide samples\ASPNET Example code that use the SDK, in subdirectories samples\cert sdk-seller.p12 API certificate for API user sdkseller_api1.sdk.com src Visual Studio project files and SDK source files. This folder is present only if you installed the source of the SDK. Optional Custom Configurations in Web.config You can add optional custom settings to the Web.config file. Adding PayPal Settings First, add a
tag, as shown below. The section must be enclosed in that comes immediately after the top-level tag.
The optional custom settings themselves are in a block later in the file: ... custom settings ... SDK Logging The PayPal SDK uses log4net public domain logging software. For information about log4net, see the log4net documentation at http://logging.apache.org/log4net/release/manual/introduction.html. This section describes SDK logging levels, in which configuration files you set the desired level, and request logging. Name-Value Pair API Developer Guide and Reference April 2007 111 The ASP.NET SDK Installing the ASP.NET SDK Log Levels The SDK varies the amount of detail it records according to four logging levels. TABLE E.4 SDK Logging Levels Level Description ALL Same as DEBUG ERROR Log only severe errors INFO Date/time of API operation, operation name, elapsed time, success or failure indication DEBUG Full text of requests and responses and other debugging messages. DEBUG logging can degrade the performance of the SDK. Be careful about using it for day-to-day operation. N O T E : Because requests and responses are asynchronous, the recording of requests and responses might appear out of sequence in the log file. Setting SDK Log Levels To enable logging for your SDK-based web applications, add the following lines inside the block of the Web.config file. You can copy these lines from the SDK_root\samples\ASPNET\Web.config file. z z You might want to change the value of the file element to write log records to a location you prefer. Set the value of the level element to the desired detail described in Table E.4, “SDK Logging Levels.”
112 April 2007 Name-Value Pair API Developer Guide and Reference The ASP.NET SDK Complete SDK and API Class Documentation Enabling Proxy Support If your application is behind a proxy server, you must enable proxy support in the Web.config file. For details on how to use the system.net element in the Web.config file, please refer to Configuring Internet Applications in the MSDN Library. Uninstalling the SDK To uninstall the SDK, use the Microsoft Windows control panel Add/Remove Programs. Complete SDK and API Class Documentation Complete Microsoft .NET Ndoc documentation for all PayPal SDK interfaces, classes, methods, structures, and data types are included with the SDK distribution. To view the documentation, open the following file with your web browser: SDK_root/docs/PayPalBaseAPI.chm Profiles Before the SDK can be used, it must know the profile of the user accessing its services. A profile is a collection of information about a merchant or developer who uses the PayPal SDK. An API profile is associated with API Services and includes: z z z z z A PayPal API username and password. If you are using API certificates, the path to the API certificate in P12 format and the private key password to that certificate. If you are using API signatures, the signature string. The optional name of a third-party who authorizes the caller to invoke PayPal APIs on his behalf. This third-party is called a subject. The PayPal environment for processing API calls: live or sandbox. An EWP profile is associated with EWP Services includes: z The path to the merchant’s local copy of that public certificate z The private key password for that public certificate z The path to a merchant’s private key file for digitally signing data Name-Value Pair API Developer Guide and Reference April 2007 113 The ASP.NET SDK Profiles z z The URL to which the button form POSTs The optional URL of a payment button image. The default is PayPal’s standard Buy Now button. For more information about how EWP works, see the Website Payments Standard Integration Guide, available at https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_IntegrationGuide.pdf. Overview to Profile-related Classes The primary interfaces and classes for SDK profiles are described in Table E.5, “Summary of ASP.NET SDK Profile-related Interfaces and Classes.” TABLE E.5 114 Summary of ASP.NET SDK Profile-related Interfaces and Classes Interface/Class Description IAPIProfile interface This interface defines the basic information that PayPal needs to know about a user of the PayPal Web Service APIs. Developers must create an instance of IAPIProfile for each account that accesses the APIs. For single-merchant developers, only a single IAPIProfile instance is needed. PayPal provides a default implementation class called DefaultAPIProfile suitable for the needs of most SDK developers. However, you are free to write a custom implementation if you need additional functionality the default class does not offer. ProfileFactory class This class creates the IAPIProfile object. It contains static methods that handle the instantiation and construction of profile objects. EWPProfile interface This interface defines the basic information that PayPal needs to know about a user of PayPal’s Encrypted Website Payments (EWP) service. Developers must create an instance of EWPProfile for each account that generates the encrypted button code; for single-merchant users this will just be a single instance). PayPal provides a basic implementation class called DefaultEWPProfile suitable for the needs of most SDK developers. However, you are free to write a custom implementation if you need functionality the default class does not offer. April 2007 Name-Value Pair API Developer Guide and Reference The ASP.NET SDK Sample Applications Sample Applications The PayPal SDK includes sample applications in the SDK_root\samples\ASPNET folder. The samples\ASPNET folder is divided into subfolders by products. TABLE E.6 Samples by Product Subfolder in SDK_Root\samples\ASPNET Products GetTransactionDetails MassPay RefundTransaction TransactionSearch wppro Express Checkout Sample API User with API Signature The samples come with an API signature for use with the samples and the PayPal Sandbox. This API signature belongs to the following user: TABLE E.7 Details of the Sample API Signature API username sdk-three_api1.sdk.com API password QFZCWN5HZM8VBG7Q API signature A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU IMPO RTANT: You must protect the API signature values 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 executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production. Name-Value Pair API Developer Guide and Reference April 2007 115 The ASP.NET SDK Sample API User with API Certificate Sample API User with API Certificate The samples come with an API digital certificate for use with the SDK and the PayPal Sandbox. This certificate belongs to the following user: TABLE E.8 Details of the SDK Sample API Certificate Location of Certificate SDK_root\samples\Certs\sdk-seller.p12 API Username sdk-seller_api1.sdk.com API Password 12345678 PKCS12 Passphrase password IMPO RTANT: You must protect the API Certificate values 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 executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production. Installing the Samples in IIS N O T E : Be sure you are logged in as an administrator, IIS running, and WinHttpCertCfg.exe is in your PATH. To install the samples in Microsoft IIS: 1. Run SDK_root\samples\ASPNET\InstallSample.bat. 2. To enable logging, change the permissions on the localComputerName\ASPNET folder to Full Control. InstallSample.bat does the following: – Creates a virtual directory named PaypalASPNETSample in IIS that points to SDK_root\samples\ASPNET. – Loads the sample API certificate SDK_root\samples\Certs\sdk-seller.p12 into the Microsoft Windows system store. – Uses the WinHttpCertCfg.exe command to grant unlimited access for account Everyone to that certificate. Running the Samples To run the samples, in Internet Explorer, open http://localhost/PaypalASPNETSamples. 116 April 2007 Name-Value Pair API Developer Guide and Reference F Country Codes N O T E : This table lists country codes defined by ISO 3166-1. Table 1: Country Codes Country Code BELARUS BY BELGIUM BE Country Code BELIZE BZ AFGHANISTAN AF BENIN BJ ÅLAND ISLANDS AX BERMUDA BM ALBANIA AL BHUTAN BT ALGERIA DZ BOLIVIA BO AMERICAN SAMOA AS BOSNIA AND HERZEGOVINA BA ANDORRA AD BOTSWANA BW ANGOLA AO BOUVET ISLAND BV ANGUILLA AI BRAZIL BR ANTARCTICA AQ IO ANTIGUA AND BARBUDA AG BRITISH INDIAN OCEAN TERRITORY ARGENTINA AR BRUNEI DARUSSALAM BN ARMENIA AM BULGARIA BG ARUBA AW BURKINA FASO BF AUSTRALIA AU BURUNDI BI AUSTRIA AT CAMBODIA KH AZERBAIJAN AZ CAMEROON CM BAHAMAS BS CANADA CA BAHRAIN BH CAPE VERDE CV BANGLADESH BD CAYMAN ISLANDS KY BARBADOS BB CENTRAL AFRICAN REPUBLIC CF CHAD TD 117 Country Codes 118 Country Code Country Code CHILE CL FK CHINA CN FALKLAND ISLANDS (MALVINAS) CHRISTMAS ISLAND CX FAROE ISLANDS FO COCOS (KEELING) ISLANDS CC FIJI FJ COLOMBIA CO FINLAND FI COMOROS KM FRANCE FR CONGO CG FRENCH GUIANA GF CONGO, THE DEMOCRATIC REPUBLIC OF THE CD FRENCH POLYNESIA PF TF COOK ISLANDS CK FRENCH SOUTHERN TERRITORIES COSTA RICA CR GABON GA COTE D'IVOIRE CI GAMBIA GM CROATIA HR GEORGIA GE CUBA CU GERMANY DE CYPRUS CY GHANA GH CZECH REPUBLIC CZ GIBRALTAR GI DENMARK DK GREECE GR DJIBOUTI DJ GREENLAND GL DOMINICA DM GRENADA GD DOMINICAN REPUBLIC DO GUADELOUPE GP ECUADOR EC GUAM GU EGYPT EG GUATEMALA GT EL SALVADOR SV GUERNSEY GG EQUATORIAL GUINEA GQ GUINEA GN ERITREA ER GUINEA-BISSAU GW ESTONIA EE GUYANA GY ETHIOPIA ET HAITI HT Country Code Country Code HEARD ISLAND AND MCDONALD ISLANDS HM LATVIA LV LEBANON LB HOLY SEE (VATICAN CITY STATE) VA LESOTHO LS HONDURAS HN LIBERIA LR HONG KONG HK LIBYAN ARAB JAMAHIRIYA LY HUNGARY HU LIECHTENSTEIN LI ICELAND IS LITHUANIA LT INDIA IN LUXEMBOURG LU INDONESIA ID MACAO MO IRAN, ISLAMIC REPUBLIC OF IR MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF MK IRAQ IQ MADAGASCAR MG IRELAND IE MALAWI MW ISLE OF MAN IM MALAYSIA MY ISRAEL IL MALDIVES MV ITALY IT MALI ML JAMAICA JM MALTA MT JAPAN JP MARSHALL ISLANDS MH JERSEY JE MARTINIQUE MQ JORDAN JO MAURITANIA MR KAZAKHSTAN KZ MAURITIUS MU KENYA KE MAYOTTE YT KIRIBATI KI MEXICO MX KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF KP MICRONESIA, FEDERATED STATES OF FM KOREA, REPUBLIC OF KR MOLDOVA, REPUBLIC OF MD KUWAIT KW MONACO MC KYRGYZSTAN KG MONGOLIA MN LAO PEOPLE'S DEMOCRATIC REPUBLIC LA MONTSERRAT MS Country Codes 120 Country Code Country Code MOROCCO MA PHILIPPINES PH MOZAMBIQUE MZ PITCAIRN PN MYANMAR MM POLAND PL NAMIBIA NA PORTUGAL PT NAURU NR PUERTO RICO PR NEPAL NP QATAR QA NETHERLANDS NL REUNION RE NETHERLANDS ANTILLES AN ROMANIA RO NEW CALEDONIA NC RUSSIAN FEDERATION RU NEW ZEALAND NZ RWANDA RW NICARAGUA NI SAINT HELENA SH NIGER NE SAINT KITTS AND NEVIS KN NIGERIA NG SAINT LUCIA LC NIUE NU SAINT PIERRE AND MIQUELON PM NORFOLK ISLAND NF VC NORTHERN MARIANA ISLANDS MP SAINT VINCENT AND THE GRENADINES SAMOA WS NORWAY NO SAN MARINO SM OMAN OM SAO TOME AND PRINCIPE ST PAKISTAN PK SAUDI ARABIA SA PALAU PW SENEGAL SN PALESTINIAN TERRITORY, OCCUPIED PS SERBIA AND MONTENEGRO CS SEYCHELLES SC PANAMA PA SIERRA LEONE SL PAPUA NEW GUINEA PG SINGAPORE SG PARAGUAY PY SLOVAKIA SK PERU PE SLOVENIA SI Country Code Country Code SOLOMON ISLANDS SB UGANDA UG SOMALIA SO UKRAINE UA SOUTH AFRICA ZA UNITED ARAB EMIRATES AE SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS GS UNITED KINGDOM GB UNITED STATES US SPAIN ES LK UNITED STATES MINOR OUTLYING ISLANDS UM SRI LANKA SUDAN SD URUGUAY UY SURINAME SR UZBEKISTAN UZ SVALBARD AND JAN MAYEN SJ VANUATU VU SWAZILAND SZ VENEZUELA VE SWEDEN SE VIET NAM VN SWITZERLAND CH VIRGIN ISLANDS, BRITISH VG SYRIAN ARAB REPUBLIC SY VIRGIN ISLANDS, U.S. VI TAIWAN, PROVINCE OF CHINA TW WALLIS AND FUTUNA WF TAJIKISTAN TJ WESTERN SAHARA EH TANZANIA, UNITED REPUBLIC OF TZ YEMEN YE ZAMBIA ZM THAILAND TH ZIMBABWE ZW TIMOR-LESTE TL TOGO TG TOKELAU TK TONGA TO TRINIDAD AND TOBAGO TT TUNISIA TN TURKEY TR TURKMENISTAN TM TURKS AND CAICOS ISLANDS TC TUVALU TV Country Codes 122 Index A C ACCT 51 ACK 15, 16, 63 Add/Remove Programs 113 ADDRESSOWNER 55 ADDRESSSTATUS 43, 55 ADDROVERRIDE 38 AMT 31 DoExpressCheckoutPayment 44 DoExpressCheckoutPayment response 48 GetTransactionDetails response 56 refunding 31 RefundTransaction 50 SetExpressCheckout 37 TransactionSearch 52 API certificate 10, 16 API credentials 14 getting 10 setting up 11 API parameters 15 API Password 10, 98, 108, 115 API signature 10, 16 api.sandbox.paypal.com 16 api-3t.paypal.com 16 api-3t.sandbox.paypal.com 16 APIProfile interface 106 AUCTIONITEMNUMBER 52 AUD 35 Australian Dollar 35 AuthorizationID 47 CAD 35 Canadian Dollar 35 Canceled-Reversal 57 CANCELURL 36 certificate sample 108, 116 CertificateAPIProfile class 106 CHF 35 chm documentation 113 CLASSPATH 104 CLOSINGDATE 60 ColdFusion 101 Completed 57 CORRELATIONID 15, 16, 63 COUNTRYCODE 42 currency codes 35 CURRENCYCODE 37, 45, 48, 60 CUSTOM 38, 43, 44, 58 Czech Koruna 35 CZK 35 B BANKTXNPENDINGURL 37 BUILD 15, 16, 63 BUSINESS 42 BUTTONSOURCE 44 BUYERID 60 Name-Value Pair API Developer Guide and Reference D Danish Krone 35 DefaultAPIProfile class 114 Denied 57 Denied (transaction status) 53 DESC 37, 44 digital certificate sample 108, 116 DKK 35 documentation 111 E EFFECTIVEDATE 59 EMAIL 37, 42, 55 TransactionSearch 51 EMAILSUBJECT 61 ENDDATE 51 March 2007 123 Index EUR 35 Euro 35 EWP profile defined 106, 113 EWPProfile interface 107, 114 EXCHANGERATE 48, 57 Expired 57 Express Checkout 107, 115 J Japanese Yen 36 Java Development Kit 1.4 103 Javadoc documentation for PayPal SDK 105 JPY 36 JSP 107 K F FEEAMT 48, 57 FEEREFUNDAMT 50 FIRSTNAME 42, 51, 55 Forint 36 G GBP 35 Get Transaction Details 115 GetTransactionDetails 33, 107 GIROPAYCANCELURL 37 GIROPAYSUCCESSURL 36 GROSSREFUNDAMT 50 H HANDLINGAMT 27, 45 HDRBACKCOLOR 39 HDRBORDERCOLOR 39 HDRIMG 39 HKD 36 Hong Kong Dollar 36 HUF 36 Hungarian Forint 36 I IAPIProfile interface 114 IIS 116 Including a Note with the Refund 32 InstallSample.bat 116 INVNUM 38, 43, 44, 51, 58 ITEMAMT 27, 45 124 Koruna 35 Krona 36 Krone 35 L L 46 L_AMTn 26, 46, 54, 59, 60 L_DESCn 59 L_EMAILn 53, 60 L_FEEAMTn 54 L_NAMEn 26, 45, 53 L_NETAMTn 54 L_NOTEn 61 L_NUMBERn 26, 46, 59 L_OPTIONSn 59 L_QTY 46 L_QTYn 26, 46, 59 L_RECEIVERIDn 60 L_STATUSn 53 L_TAXAMTn 26, 46 L_TIMESTAMPn 53 L_TIMEZONEn 53 L_TRANSACTIONIDn 53 L_TYPEn 53 L_UNIQUEIDn 61 LASTNAME 42, 52, 55 LOCALECODE 39 log4j.properties 105 log4net 111 logging levels 112 M MassPay 115 MAXAMT 37 METHOD 15 March 2007 Name-Value Pair API Developer Guide and Reference Index DoExpressCheckoutPayment 44 GetExpressCheckoutDetails 41 GetTransactionDetails 54 MassPay 60 RefundTransaction 50 SetExpressCheckout 36 TransactionSearch 51 Microsoft .NET 1.1 109 MIDDLENAME 42, 52, 55 MULTIITEM 60 N NETREFUNDAMT 50 New Zealand Dollar 36 NOK 36 Norwegian Krone 36 NOSHIPPING 38 NOTE GetTransactionDetails response 58 RefundTransaction 50 NOTIFYURL 45 NVP format 12 posting 16 request creating and posting 11 interpreting 11 request format 14 request-response model 12 response format 15 ACK values 16 error 16 NZD 36 O ORDERTIME 48, 56 P PAGESTYLE 39 PARENTTRANSACTIONID 56 PASSWORD 59 PAYERBUSINESS 55 PAYERID 42, 44, 55 PAYERSTATUS 42, 55 Name-Value Pair API Developer Guide and Reference PAYFLOWCOLOR 39 PAYMENTACTION 37, 44 PaymentAction 47 PAYMENTSTATUS 49, 57 PAYMENTTYPE 48, 56 PayPal API servers API certificate 16 API signature 16 PayPal business account setting up 11 paypal tag in Web.Config 111 PayPal-supported currencies 35 Pending 57 Pending (transaction status) 53 PENDINGREASON 49, 58 PendingReason 57 PERIOD 60 PHONENUM 40, 43 PLN 36 Polish Zloty 36 Pound Sterling 35 Processed 57 Processing (transaction status) 53 ProfileFactory class 107, 114 Profiles class 107 PWD 14 R REASONCODE 49, 58 ReasonCode 57 REATTEMPT 59 RECEIPTID 51, 56 RECEIVER 51 RECEIVERBUSINESS 54 RECEIVEREMAIL 54 RECEIVERID 54 RECEIVERTYPE 60 RECURRENCES 59 RECURRING 60 REDIRECTREQUIRED 43, 49 Refunded 57 Refunding A Partial Amount 31 Refunding The Full Amount of a Transaction 31 RefundTransaction 31, 107, 115 REFUNDTRANSACTIONID 50 REFUNDTYPE 31, 50 March 2007 125 Index SUBSCRIPTIONID 59 Success (transaction status) 53 successResponseFields, defined 15 SUFFIX 42, 52, 55 Swedish Krona 36 Swiss Franc 35 system store 116 REQCONFIRMSHIPPING 38 RETRYTIME 59 RETURNURL 36 Reversed 57 Reversed (transaction status) 53 S SALESTAX 58 SALUTATION 42, 51, 55 Sample API Certificate 108, 116 sample API credentials 10, 98, 108, 115, 116 Sample API Signature 10, 98, 108, 115 sample application 115 SampleApp 107 Sandbox 16 sdk-seller.p12 108, 111, 116 sdk-seller_api1.sdk.com 10, 98, 108, 115, 116 sdk-three_api1.sdk.com 10, 98, 108, 115 security parameters required 14 SEK 36 servers PayPal API API certificate 16 API signature 16 Service Pack 1 for Microsoft .NET Framework 1.1 110 SETTLEAMT 48, 57 SGD 36 SHIPPINGAMT 27, 45 SHIPTOCITY 40, 43, 46, 55 SHIPTOCOUNTRYCODE 40, 43, 47, 55 SHIPTONAME 40, 42, 46, 55 SHIPTOPHONENUM 47, 55 SHIPTOSTATE 40, 43, 47, 56 SHIPTOSTREET 40, 42, 46, 56 SHIPTOSTREET2 40, 43, 47, 56 SHIPTOZIP 40, 43, 47, 55 SIGNATURE 14 SignatureAPIProfile class 106 Singapore Dollar 36 source files 111 src 111 STARTDATE 32, 51 STATUS 53 SUBJECT 14 SUBSCRIPTIONDATE 59 126 T TAXAMT 27, 45, 48, 57 TOKEN 47 DoExpressCheckoutPayment 44 GetExpressCheckoutDetails 41 GetExpressCheckoutDetails response 42 SetExpressCheckout 38 SetExpressCheckout response 41 Token 18, 41 token 18, 41 TRANSACTIONCLASS 52 TRANSACTIONID DoExpressCheckoutPayment response 47 GetTransactionDetails 54 GetTransactionDetails response 56 RefundTransaction 50 TransactionSearch 51 TransactionSearch 32, 107, 115 TRANSACTIONTYPE 47, 56 TransactionType 49, 58 U U.S. Dollar 36 URL format 12 UrlDecode 13 urldecode() 13 URLDecoder 13 URLDecodeurlEncodedString 13 URLEncode 13 UrlEncode 13 urlencode() 13 URL-encoded string 14 URLEncodedFormatstring 13 URLEncoder.encode 13 URL-encoding 13, 15, 16, 35 ASP.NET 13 Classic ASP 13 March 2007 Name-Value Pair API Developer Guide and Reference Index ColdFusion 13 Java 13 PHP 13 USD 36 USER 14 USERNAME 59 UTC/GMT 53 V VERSION 15, 16, 63 VERSION=2.3 14 Voided 57 W Web.config 111, 112 paypal tag 111 Website Payments Standard Integration Guide 106, 114 WinHttpCertCfg.exe 116 WinHttpPCertCfg.exe 116 Y Yen 36 Z Zloty 36 Name-Value Pair API Developer Guide and Reference March 2007 127

Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
Page Mode                       : UseOutlines
XMP Toolkit                     : Adobe XMP Core 4.0-c316 44.253921, Sun Oct 01 2006 17:14:39
Producer                        : Acrobat Distiller 8.1.0 (Windows)
Creator Tool                    : FrameMaker 7.2
Modify Date                     : 2007:12:10 16:34:08Z
Create Date                     : 2007:12:10 16:34:08Z
Format                          : application/pdf
Title                           : PayPal Name-Value Pair API Developer Guide and Reference
Creator                         : PayPal, Inc.
Document ID                     : uuid:2970a8d1-a1f2-4871-9f76-854c3cb788ec
Instance ID                     : uuid:818db4a4-0a18-4baf-b212-0cd97005189d
Page Count                      : 127
Author                          : PayPal, Inc.
EXIF Metadata provided by EXIF.tools

Navigation menu