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
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
1
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:
N
[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:
<form method=post
action=https://api-3t.sandbox.paypal.com/nvp>
<!-- UNPROTECTED VALUES. DO NOT USE IN PRODUCTION! -->
<input type=hidden name=USER value=xxxxxx.paypal.com>
<input type=hidden name=PWD value=abcdefg>
<input type=hidden name=SIGNATURE value=xxxxxxxxxxxxxxx>
...
</form>
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.
T
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
2
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
2
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
2
&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
2
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.
No
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
2
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.
E
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
2
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
2
&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
2
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
2
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
2
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
2
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
2
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
2
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
2
Updating the Shipping Address Using DoExpressCheckoutPayment
30 April 2007 Name-Value Pair API Developer Guide and Reference
Loading...