PayPal Name-Value Pair API - 2007 Reference Manual

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

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.

https://developer.paypal.com/ by entering your email address and

Name-Value Pair API Developer Guide and Reference April 2007 7

Preface

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 Bug fixes including updating Line Item Details for Express Checkout APIs, dding

December 2006 Updates for bug fixes.

October 2006 First public release.

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

8 April 2007 Name-Value Pair API Developer Guide and Reference

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 OTE: 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 OTE: If you are using the samples, this signature is already in the code.

TABLE 1.1 Details of the Sample API Signature

API username sdk-three_api1.sdk.com

API password QFZCWN5HZM8VBG7Q

API signature A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU

10 April 2007 Name-Value Pair API Developer Guide and Reference

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.

Overview

Taking Your Application Live

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

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.

www.paypal.com.

Name-Value Pair API Developer Guide and Reference April 2007 11

Overview

Technical Details

IMPORTANT: If you are using API signature, you must protect the API signature values in

N OTE: 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.

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.

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 The NVP string is URL-encoded.

12 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 Method

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

Encoding.Default)

Decode System.Web.HttpUtility.UrlDecode(buffer,

Encoding.Default)

Classic ASP

Java Encode java.net.URLEncoder.encode

PHP Encode urlencode()

ColdFusion Encode URLEncodedFormatstring [, charset ]

Encode Server.URLEncode

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

Internet.

Decode java.net.URLDecoder.decode

Decode urldecode()

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

Body Parameters

USER=apiUsername&PWD=apiPassword&SIGNATURE=apiSignature

&SUBJECT=optionalThirdPartyEmailAddress&VERSION=2.3

The following parameters are always required:

USER

PWD

VERSION=2.3

OTE: The examples show the required security parameters like this:

[requiredSecurityParameters]

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

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

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

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

API Response Fields

ACK=Success&TIMESTAMP=date/timeOfResponse

&CORRELATIONID=debuggingToken&VERSION=2.300000

&BUILD=buildNumber

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

The examples show the successful response header fields like this:

[successResponseFields]

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

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.

ACK=Error&TIMESTAMP=date/timeOfResponse&

CORRELATIONID=debuggingToken&VERSION=2.300000&

BUILD=buildNumber&L_ERRORCODE0=errorCode&

L_SHORTMESSAGE0=shortMessage

L_LONGMESSAGE0=longMessage

&L_SEVERITYCODE0=severityCode

ABLE 1.7 ACK Parameter Values

Type of Response Value

Successful response Success

SuccessWithWarning

Error response Error

Warning

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

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

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 OTE: 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

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

&METHOD=SetExpressCheckout&AMT=10.00&

&TOKEN=EC-3DJ78083ES565113B

Request

Response

[requiredSecurityParameters]

RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html

[successResponseFields]

N OTE: 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

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

&METHOD=GetExpressCheckoutDetails&

&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com&

Request

Response

[requiredSecurityParameters]

TOKEN=EC-3DJ78083ES565113B

[successResponseFields]

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

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

[requiredSecurityParameters]

TOKEN=EC-0E881823PA052770A&AMT=10.00&

Request

Name-Value Pair API Developer Guide and Reference April 2007 19

PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale

&METHOD=DoExpressCheckoutPayment&

Accepting PayPal in Express Checkout

Support giropay and electronic funds transfer

TOKEN=EC-0E881823PA052770A&

Response

[successResponseFields&

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.

GIROPAYCANCELURL giropayCancelURL The URL on the merchant site to

BANKTXNPENDINGURL BanktxnPendingURL The URL on the merchant site to

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.

No redirect to after a giropay or bank transfer payment is cancelled or fails.

No transfer to after a bank transfer payment.

20 April 2007 Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Controlling the Shipping Address Using SetExpressCheckout

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 OTE: 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.

XAMPLE 2.1 Suppressing the Shipping Address

&METHOD=SetExpressCheckout&AMT=10.00&

&TOKEN=EC-17C76533PL706494P

Request

Response

[requiredSecurityParameters]

RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &NOSHIPPING=1

[successResponseFields]

Name-Value Pair API Developer Guide and Reference April 2007 21

Accepting PayPal in Express Checkout

Controlling the Shipping Address Using SetExpressCheckout

GetExpressCheckoutDetails does not return the shipping address.

EXAMPLE 2.2 GetExpressCheckoutDetails

&METHOD=GetExpressCheckoutDetails&

&TOKEN=EC-

Request

Response

[requiredSecurityParameters]

TOKEN=EC-17C76533PL706494P

[successResponseFields]

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]

RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &SHIPTONAME=Peter+Smith& &SHIPTOSTATE=CA&SHIPTOCOUNTRYCODE=US&SHIPTOZIP=99911&

ADDROVERRIDE=1

&METHOD=SetExpressCheckout&AMT=10.00&

SHIPTOSTREET=144+Main+St.&SHIPTOCITY=SAN+JOSE

Response

[successResponseFields]

&TOKEN=EC-17C76533PL706494P

GetExpressCheckoutDetails returns the overridden shipping address.

EXAMPLE 2.4 GetExpressCheckoutDetails

Request

Response

[requiredSecurityParameters]

17C76533PL706494P

[successResponseFields]

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

&METHOD=GetExpressCheckoutDetails&TOKEN=EC-

&TOKEN=EC-17C76533PL706494P&

22 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

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

&METHOD=SetExpressCheckout&AMT=10.00&

&TOKEN=EC-17C76533PL706494P

Request

Response

[requiredSecurityParameters]

CURRENCYCODE=EUR& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html &LOCALECODE=fr_FR

[successResponseFields]

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

[requiredSecurityParameters]

RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html&

Request

Response

Name-Value Pair API Developer Guide and Reference April 2007 23

PAGESTYLE=DesignerFotos-Yellow

[successResponseFields]

&METHOD=SetExpressCheckout&AMT=10.00&

&TOKEN=EC-17C76533PL706494P

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 HDRBACKCOLOR: set the background color for the background of the header of the payment

page

z PAYFLOWCOLOR: set the background color for the payment page

EXAMPLE 2.7 Specifying Logo and Color Settings Individually

&METHOD=SetExpressCheckout&AMT=10.00&

&TOKEN=EC-17C76533PL706494P

Request

Response

[requiredSecurityParameters]

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

[successResponseFields]

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]

TOKEN=EC-3DJ78083ES565113B

&METHOD=GetExpressCheckoutDetails&

&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com&

Response

[successResponseFields]

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

24 April 2007 Name-Value Pair API Developer Guide and Reference

Accepting PayPal in Express Checkout

Making a Sale Using DoExpressCheckoutPayment

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 OTE: 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

[requiredSecurityParameters]

TOKEN=EC-8AX1275942659774U&PAYERID=95HR9CM6D56Q2&AMT=10.00&

Request

Name-Value Pair API Developer Guide and Reference April 2007 25

PAYMENTACTION=Sale&NOTIFYURL=https://www.anycompany.com/process-ipn/

&METHOD=DoExpressCheckoutPayment&

Accepting PayPal in Express Checkout

Including Line Item Details Using DoExpressCheckoutPayment

&TOKEN=EC-8AX1275942659774U&

Response

[successResponseFields]

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

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

&METHOD=DoExpressCheckoutPayment&

&TOKEN=EC-4XH62109C8044521N&

n, you must specify the TAXAMT parameter. The values for

Request

Response

[requiredSecurityParameters]

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]

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_AMT L_QTY

n should add up to the ITEMAMT.

n, you must specify the ITEMAMT parameter. The values for L_AMTn and

If you specify L_TAXAMT L_TAXAMT

n 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

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 OTE: 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 OTE: 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

&METHOD=DoExpressCheckoutPayment

&TOKEN=EC-

Request

Response

[requiredSecurityParameters]

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]

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

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

&METHOD=DoExpressCheckoutPayment&

&TOKEN=EC-

Request

Response

[requiredSecurityParameters]

TOKEN=

5JA9268562132991T&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=10.00& DESC=Order+for+5+books&CUSTOM=Thank+you+for+your+business!&INVNUM=ABC1234567

EC-

[successResponseFields]

5JA9268562132991T&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

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:

z SHIPTONAME z SHIPTOSTREET z SHIPTOSTREET2 z SHIPTOCITY z SHIPTOSTATE z SHIPTOCOUNTRYCODE z SHIPTOPHONENUM

z SHIPTOZIP

28 April 2007 Name-Value Pair API Developer Guide and Reference

Updating the Shipping Address Using DoExpressCheckoutPayment

EXAMPLE 2.13 Updating the Shipping Address

Accepting PayPal in Express Checkout

Request

Response

[requiredSecurityParameters]

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]

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

&METHOD=DoExpressCheckoutPayment&

&TOKEN=EC-47C20533CU265432F&

Name-Value Pair API Developer Guide and Reference April 2007 29

Accepting PayPal in Express Checkout

Updating the Shipping Address Using DoExpressCheckoutPayment

30 April 2007 Name-Value Pair API Developer Guide and Reference

+ 97 hidden pages