Académique Documents
Professionnel Documents
Culture Documents
For Professional Use Only Currently only available in English. A usage Professional Uniquement Disponible en Anglais uniquement pour l'instant.
PayPal Name-Value Pair API Developer Guide and Reference Document Number: 100018.en_US-200702
2006 PayPal, Inc. All rights reserved. PayPal and the PayPal logo are registered trademarks 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. PayPal, Inc. does not guarantee that the features described in this document will be announced or made available to anyone in the future.
Contents
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Notational Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Documentation Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Chapter 1
Creating Name-Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Developing with the PayPal NVP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Business Functions of the NVP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Chapter 2
2. HTTPS Posting the Request to PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . 15 API Servers for API Certificate Security . . . . . . . . . . . . . . . . . . . . . . . . . 16 API Servers for API Signature Security . . . . . . . . . . . . . . . . . . . . . . . . . 16 3. Processing the Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 URL-Decoding the Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 3
Final Sale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Authorizing a Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Recording the Final Shipping Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Including Subtotals of Item Cost, Shipping, Handling, and Tax . . . . . . . . . . . . . . . 21
February 2007
Contents
Chapter 4
Controlling the Shipping Address Using SetExpressCheckout . . . . . . . . . . . . . . . 26 Requiring a Confirmed Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Suppressing Display of Shipping Address on PayPal . . . . . . . . . . . . . . . . . . 26 Overriding the Shipping Address Stored on PayPal . . . . . . . . . . . . . . . . . . . 27 Changing the Language on the PayPal Login Page Using SetExpressCheckout . . . . . . 28 Changing the Logo on the PayPal Pages Using SetExpressCheckout . . . . . . . . . . . 28 Specifying a Custom Payment Page Style. . . . . . . . . . . . . . . . . . . . . . . . 28 Specifying Logo and Color Settings Individually . . . . . . . . . . . . . . . . . . . . . 29 Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails. . . . . . . . 30 Making a Sale Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . 31 Authorizing for Single Capture Using SetExpressCheckout and DoExpressCheckoutPayment. 31 Authorizing for Multiple Captures Using SetExpressCheckout and DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Changing the URL for IPN Using DoExpressCheckoutPayment . . . . . . . . . . . . . . 32 Including Line Item Details Using DoExpressCheckoutPayment . . . . . . . . . . . . . . 33 Including Subtotals Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . 34 Updating Order Details Using DoExpressCheckoutPayment . . . . . . . . . . . . . . . . 34 Updating the Shipping Address Using DoExpressCheckoutPayment . . . . . . . . . . . . 35
Chapter 5
Back-Office Administration . . . . . . . . . . . . . . . . . 37
Making a Single Capture Against an Order Using DoCapture. . . . . . . . . . . . . . 37 Making Multiple Partial Captures Against an Order Using DoCapture . . . . . . . . . 38 Including an Invoice Number and Note on the Capture Using DoCapture . . . . . . . 39
Refunding Using RefundTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Full Refund. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Partial Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Including a Note with the Refund . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Searching for Transactions Using TransactionSearch . . . . . . . . . . . . . . . . . . . . 41
February 2007
Contents
February 2007
Contents
February 2007
Contents
Optional Custom Configurations in Web.config . . . . . . . . . . . . . . . . . . . . .147 SDK Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147 Enabling Proxy Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 Uninstalling the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 Complete SDK and API Class Documentation. . . . . . . . . . . . . . . . . . . . . . . .149 Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 Overview to Profile-related Classes . . . . . . . . . . . . . . . . . . . . . . . . . . .150 Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150 Sample API User with API Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . .151 Sample API User with API Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . .152 Installing the Samples in IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152 Running the Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Appendix F
Country Codes
. . . . . . . . . . . . . . . . . . . . . . 155
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
February 2007
Contents
February 2007
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.
Notational Conventions
This document uses typefaces to identify the characteristics of text. These typefaces and the characteristics they imply are described below:
Typeface
serif italics
How Used
A document title. A term being discussed or defined. For example: A file is a readable or writable stream of characters Boolean values (not keywords). For example: The function returns true if it encounters an error.
monospaced
Pathnames or file names that appear in body text frames. Code-related names that appear in body text frames. Such names are used for functions, callbacks, arguments, data structures, and fields. For example: AbstractResponseType is the SOAP response type definition on which all PayPal API response methods are based. Components of Internet protocol requests and responses, such as HTTPS and FORM variables. For example: The PayPal system uses a method=POST request to return IPN status variables related to subscriptions, such as txn_type.
Serif bold
User interface names, such as window names or menu selections. For example: On the Profile page, click Email to confirm your email address
February 2007
Preface
Documentation Problems
Typeface
San-serif oblique
How Used
Placeholders used in the context of a format or programming standard or formal descriptions of PayPal system syntax. Placeholders indicate values or names that the reader should provide. Example: For example, amount is the variable for a single-item shopping cart, but amount_X is the name of the variable for a multi-item shopping cart. amount_3 is the item amount for the third item in a multiple-item shopping cart.
To convey additional information, this document may also apply color and underlining to words or phrases that use the typefaces described above. Such use is described below:
Text attribute
How Used
Hypertext link to a page in the current document or to another document in the set. Hypertext link to a URL or that initiates a web action, such as sending mail.
xxxxxx
xxxxxx
Documentation Problems
If you discover any errors in or have any problems with this documentation, please email us by following the instructions below. Describe the error or problem as completely as possible and give us the document title, the date of the document, and the page number or page range. To contact Developer Technical Support about documentation problems: Log in to your account at https://developer.paypal.com/ by entering your email address and password in the Member Log In box Click Help Center at the bottom of the box on the right side of the page. Click Email PayPal Technical Support. Complete the form.
Revision History
Revision history for PayPal Name-Value Pair API Developer Guide and Reference.
TABLE P.1 Revision History Date
February 2007 Octboer
Description
Updates for bug fixes. First public release.
10
February 2007
The PayPal Name-Value Pair (NVP) API is a simple interface to PayPals business functions, risk management, and business logic. At its most basic, using the NVP API is as easy as posting a name-value pair string over an HTTPS connection to PayPals server and then processing the response, which is also a name-value pair string.
For details about the using the NVP API directly, see Appendix C, NVP API Web Samples. 2. Integrate to the NVP API through an SDK. The Java and ASP.NET SDKs provide some simple functions for integrating with the NVP API. For details about the PayPal NVP SDK, see Appendix D, The Java SDK or Appendix E, The ASP.NET SDK.
February 2007
11
Business Function Accept PayPal in checkout on your website. Get paid immediately or authorize a payment for later capture.
Charge a credit card. Get paid immediately or authorize a payment for later capture. Capture payments previously authorized through Express Checkout, DoDirectPayment, or Website Payments Standard. Make a single capture or multiple captures. Reauthorize or void previous authorizations.
Issue full or multiple partial refunds Search for your transactions by a beginning date or other criteria View the specific details about a transaction Pay multiple recipients with a single request
12
February 2007
N O T E : Before
reading this section, make sure you have set up your PayPal accounts and obtained your API Credentials as detailed on the PayPal Integration Center at:
https://www.paypal.com/IntegrationCenter/ic_certificate.html
Making a Name-Value Pair (NVP) API call consists of the following basic steps: 1. Constructing a request parameter string of name-value pairs for the specific API method. 2. HTTPS-posting the parameter string to a PayPal server. 3. Processing the name-value pairs in the response from the server.
In practice, you need to concatenate all parameters and values into a single URL-encoded string, and you can specify the parameters in any order.
February 2007
13
Value Required Required Required Optional Your PayPal API Username. Your PayPal API Password. Version number of the NVP API service. Your API signature string.
N O T E : 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.
N O T E : Set this parameter only if you are calling an API on a different users
behalf.
IMPO RTANT: You
must protect the values for USER, PWD, and SIGNATURE in your implementation. Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production. 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: <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>
All API methods and their parameters are detailed in Appendix A, NVP API Method and Field Reference. Examples of use are in Chapter 3, Charging a Credit Card Using
14
February 2007
DoDirectPayment, Chapter 4, Accepting PayPal in Express Checkout, and Chapter 5, Back-Office Administration.
URL-Encoding Methods
You need to URL-encode the values of parameters in the request string so that certain characters like & and spaces are treated correctly. Use the following methods to ensure the proper encoding
TABLE 2.3 URL-Encoding Methods Language ASP.NET Classic ASP Java PHP ColdFusion URL-Encoding Method
System.Web.HttpUtility.UrlEncode(buffer, Encoding.Default) Server.URLEncode java.net.URLEncoder.encode urlencode() URLEncodedFormatstring [, charset ]
February 2007
15
In our examples, we show the successful response header fields like this:
[successResponseFields]
Each response includes the ACK field. If the ACK fields value is Success or SuccessWithWarning, you should process the specific 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: fill-in a FORM for your user, update your database, and so on.
16
February 2007
Error Responses
If the ACK value is Error or Warning, specific API response fields are not returned. An error response has the following general format.
TABLE 2.6 Format of an Error Response Response Fields on Error
ACK=Error&TIMESTAMP=date/timeOfResponse &CORRELATIONID=debuggingToken&VERSION=2.300000 &BUILD=buildNumber&L_ERRORCODE0=errorCode& L_SHORTMESSAGE0=shortMessage &L_LONGMESSAGE0=longMessage&L_SEVERITYCODE0=severityCode
Multiple errors can be returned. Each set of errors has a different numeric suffix, starting with 0 and incremented by one for each error.
For possible causes of errors and how to correct them, see the explanation of the specific error code, short message, and long message in Appendix B, Error Message Reference.
February 2007
17
18
February 2007
Final Sale
To charge a credit card for a final sale, include the PAYMENTACTION=Sale field.
EXAMPLE 3.1 Charging a Credit Card for a Final Sale [requiredSecurityParameters]&METHOD=DoDirectPayment&CREDITCARDTYPE=VISA &ACCT=4683075410516684&EXPDATE=012007&CVV2=808&AMT=212.95 &FIRSTNAME=Designer&LASTNAME=Fotos&IPADDRESS=255.55.167.002 &STREET=1234+Easy+Street&CITY=San+Jose&STATE=CA&COUNTRY=United+States &ZIP=95110&COUNTRYCODE=US&PAYMENTACTION=Sale
Request
Response
[successResponseFields]&AVSCODE=X&TRANSACTIONID=9CX07910UV614511L&AMT=212.95
February 2007
19
Authorizing a Payment
To authorize a credit card for later capture, include the PAYMENTACTION=Authorization field.
EXAMPLE 3.2 Authorizing a Credit Card for Later Capture [requiredSecurityParameters]&METHOD=DoDirectPayment&CREDITCARDTYPE=VISA &ACCT=4683075410516684&EXPDATE=012007&CVV2=808&AMT=305.92 &FIRSTNAME=Designer&LASTNAME=Fotos&IPADDRESS=255.55.167.002 &STREET=1234+Easy+Street&CITY=San+Jose&STATE=CA&COUNTRY=United+States &ZIP=95110&COUNTRYCODE=US&PAYMENTACTION=Authorization
Request
Response
[successResponseFields]&AVSCODE=X&TRANSACTIONID=4EL6476506322203C&AMT=305.92
To capture the payment, use DoCapture. For details, see Capturing, Authorizing, Voiding, and Reauthorizing on page 37.
20
February 2007
Response
[successResponseFields]&AVSCODE=X&TRANSACTIONID=0W099911J1541261D&AMT=212.95
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.
Request
&ITEMAMT=115.00&SHIPPINGAMT=7.02&HANDLINGAMT=1.00&TAXAMT=4.85
Response
[successResponseFields]&AVSCODE=X&TRANSACTIONID=79V13941UC416632T&AMT=127.87
February 2007
21
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.
EXAMPLE 3.5 Adding Line Item Detail [requiredSecurityParameters]&METHOD=DoDirectPayment&CREDITCARDTYPE=VISA &ACCT=4683075410516684&EXPDATE=012007&CVV2=808&AMT=127.87 &FIRSTNAME=Designer&LASTNAME=Fotos&IPADDRESS=255.55.167.002 &STREET=1234+Easy+Street&CITY=San+Jose&STATE=CA&COUNTRY=United+States &ZIP=95110&COUNTRYCODE=US&PAYMENTACTION=Sale&L_DESC0=Cat+Nibbles Request
Response
[successResponseFields]&AVSCODE=X&TRANSACTIONID=3B288546P5019992D&AMT=127.87
22
February 2007
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 Customers Browser to PayPal Login Page 3. Getting Payer Details Using GetExpressCheckoutDetails 4. Making a Sale Using DoExpressCheckoutPayment
February 2007
23
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.
Request
Response
[successResponseFields]&TOKEN=EC-3DJ78083ES565113B
N O T E : Because
Sale. Save TOKEN for use on the remaining Express Checkout calls.
For redirecting the customers 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.
24
February 2007
[successResponseFields]&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com&
PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith& COUNTRYCODE=US&SHIPTONAME=John Smith&SHIPTOSTREET=144+Main+St.& SHIPTOCITY=San+Jose&SHIPTOSTATE=CA&SHIPTOCOUNTRY=US&SHIPTOCOUNTRYNAME=United+S tates& SHIPTOZIP=99221&ADDRESSID=PayPal& ADDRESSSTATUS=Confirmed
Response
Make sure TOKEN matches the value in SetExpressCheckout response. Save PAYERID for use on the next call.
Request
February 2007
25
Response
Request
Response
[successResponseFields]&TOKEN=EC-0E881823PA052770A
Request
26
February 2007
Response
[successResponseFields]&TOKEN=EC-17C76533PL706494P
[successResponseFields]&TOKEN=ECResponse
17C76533PL706494P&EMAIL=abcdef@anycompany.com&PAYERID=95HR9CM6D56Q2& PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith&COUNTRYCODE=US& ADDRESSID=PayPal&ADDRESSSTATUS=None
Request
Response
[successResponseFields]&TOKEN=EC-17C76533PL706494P
February 2007
27
[successResponseFields]&TOKEN=EC-17C76533PL706494P&
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&SHIPTOCOUNTRY=US&SHIPTOCOUNTRYNAME=United+S tates&SHIPTOZIP=95112& ADDRESSID=PayPal&ADDRESSSTATUS=Unconfirmed
Response
Request
Response
[successResponseFields]&TOKEN=EC-17C76533PL706494P
28
February 2007
Request
Response
[successResponseFields]&TOKEN=EC-17C76533PL706494P
Request
Response
[successResponseFields]&TOKEN=EC-17C76533PL706494P
February 2007
29
[successResponseFields]&TOKEN=EC-3DJ78083ES565113B&EMAIL=abcdef@anyemail.com&
PAYERID=95HR9CM6D56Q2&PAYERSTATUS=verified&FIRSTNAME=John&LASTNAME=Smith& COUNTRYCODE=US&SHIPTONAME=John Smith&SHIPTOSTREET=144+Main+St.& SHIPTOCITY=San+Jose&SHIPTOSTATE=CA&SHIPTOCOUNTRY=US&SHIPTOCOUNTRYNAME=United+S tates&SHIPTOZIP=99221& ADDRESSID=PayPal&ADDRESSSTATUS=Confirmed
Response
Get the payer name from the following parameters in GetExpressCheckoutDetails response: SALUTATION FIRSTNAME MIDDLENAME LASTNAME SUFFIX Get the shipping address from the following parameters in GetExpressCheckoutDetails response: SHIPTONAME SHIPTOSTREET SHIPTOSTREET2 SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY SHIPTOPHONENUM SHIPTOZIP
30
February 2007
EXAMPLE 4.13 Authorizing for Single Capture in SetExpressCheckout [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=10.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html& PAYMENTACTION=Authorization
Request
Response
[successResponseFields]&
TOKEN=EC-30P862430W113011F
Request
[successResponseFields]&TOKEN=EC-30P862430W113011F&
TRANSACTIONID=4D479374VP578364Y&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:02:42Z&AMT=10.00& CURRENCYCODE=USD&TAXAMT=0.00&PAYMENTSTATUS=Pending& PENDINGREASON=authorization&REASONCODE=None
Response
Save TRANSACTIONID and use it for the value of AUTHORIZATIONID in DoCapture request. For information about DoCapture, see Capturing, Authorizing, Voiding, and Reauthorizing on page 37.
February 2007
31
EXAMPLE 4.15 Authorizing for Multiple Captures in SetExpressCheckout [requiredSecurityParameters]&METHOD=SetExpressCheckout&AMT=1.00& RETURNURL=https://www.anycompany.com/orderprocessing/orderreview.html& CANCELURL=https://www.anycompany.com/orderprocessing/shippinginfo.html& PAYMENTACTION=Order
Request
Response
[successResponseFields]&
TOKEN=EC-8NB10343BA3562027
EXAMPLE 4.16 Authorizing for Multiple Captures in DoExpressCheckoutPayment [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-8NB10343BA3562027&PAYERID=95HR9CM6D56Q2&AMT=1.00& PAYMENTACTION=Order
Request
Response
Save TRANSACTIONID and use it for the value of AUTHORIZATIONID in DoCapture request. For information about DoCapture, see Capturing, Authorizing, Voiding, and Reauthorizing on page 37.
32
February 2007
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 4.17 Changing the URL for IPN [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC-8AX1275942659774U&PAYERID=95HR9CM6D56Q2&AMT=10.00& PAYMENTACTION=Sale&NOTIFYURL=https://www.anycompany.com/process-ipn/
Request
[successResponseFields]&TOKEN=EC-8AX1275942659774U&
TRANSACTIONID=1MA55216691247718&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:39:13Z&AMT=10.00& CURRENCYCODE=USD&FEEAMT=0.59&TAXAMT=0.00&PAYMENTSTATUS=Completed& PENDINGREASON=None&REASONCODE=None
Response
Request
[successResponseFields]&TOKEN=EC-4XH62109C8044521N&
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
Response
February 2007
33
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.
Request
Response
34
February 2007
Response
Request
[successResponseFields]&TOKEN=EC-47C20533CU265432F&
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
Response
February 2007
35
36
February 2007
Back-Office Administration
This section gives you examples of the following functions: Capturing, Authorizing, Voiding, and Reauthorizing on page 37 Refunding Using RefundTransaction on page 40 Searching for Transactions Using TransactionSearch on page 41 Viewing Details of a Single Transaction Using GetTransactionDetails on page 42
use these APIs, you need to know the TRANSACTIONID of the original transaction. Use the value of the original TRANSACTIONID as the value of the AUTHORIZATIONID with DoCapture, DoAuthorization, DoVoid, and DoReauthorization.
only once is default. To be explicit, you can set COMPLETETYPE=Complete. COMPLETETYPE=Complete closes all outstanding authorizations for the order. You can not make anymore captures.
EXAMPLE 5.1 Capturing the Full Amount of an Authorization Request [requiredSecurityParameters]&METHOD=DoCapture&AUTHORIZATIONID=01987219673867 &AMT=99.12&COMPLETETYPE=Complete
February 2007
37
Back-Office Administration
Capturing, Authorizing, Voiding, and Reauthorizing
[successResponseFields]&AUTHORIZATIONID=01987219673867
&TRANSACTIONID=7JZ9679864YA2699519&PARENTTRANSACTIONID=01987219673867 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=express-checkout &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:31:38Z&AMT=99.12 &CURRENCYCODE=USD&FEEAMT=3.29&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None
Response
Response
[requiredSecurityParameters]&METHOD=DoCapture&AUTHORIZATIONID=4EL6476506322203 &AMT=103.12&COMPLETETYPE=NotComplete
Response
38
February 2007
Back-Office Administration
Capturing, Authorizing, Voiding, and Reauthorizing
[requiredSecurityParameters]&METHOD=DoCapture&AUTHORIZATIONID=4EL6476506322203 &AMT=103.12&COMPLETETYPE=Complete
[successResponseFields]&AUTHORIZATIONID=4EL6476506322203
&TRANSACTIONID=7JZ89864YA2699519&PARENTTRANSACTIONID=4EL6476506322203 &RECEIPTID=5151-0525-2028-5336&TRANSACTIONTYPE=webaccept &PAYMENTTYPE=instant&ORDERTIME=2006-08-15T17:31:38Z&AMT=90.80 &CURRENCYCODE=USD&FEEAMT=3.29&TAXAMT=0.00&PAYMENTSTATUS=Completed &PENDINGREASON=None&REASONCODE=None
Response
Response
February 2007
39
Back-Office Administration
Refunding Using RefundTransaction
R e f u n d i n g U s i n g R e f u n d Tr a n s a c t i o n
With RefundTransaction, you can refund the full amount or a partial amount of a transaction. Specify the original transaction ID and the refund type: Full or Partial.
Full Refund
IMPO RTANT: If
you refund the full amount, do not set the AMT field.
Response
[successResponseFields]&REFUNDTRANSACTIONID=4RP55200GJ177180N
&FEEREFUNDAMT=4.01&GROSSREFUNDAMT=127.87&NETREFUNDAMT=123.86
Partial Refunds
To refund a partial amount, set REFUNDTYPE to Partial and set the AMT.
EXAMPLE 5.5 Refunding A Partial Amount Request [requiredSecurityParameters]&METHOD=RefundTransaction &TRANSACTIONID=9CX07910UV614511L&REFUNDTYPE=Partial&AMT=12.95 [successResponseFields]&REFUNDTRANSACTIONID=1H0011898K637700R
&FEEREFUNDAMT=0.38&GROSSREFUNDAMT=12.95&NETREFUNDAMT=12.57
Response
Request
Response
40
February 2007
Back-Office Administration
Searching for Transactions Using TransactionSearch
Respons
TransactionSearch returns a multi-valued array of all transactions that match the search criteria. Each transaction begins with its date: L_TIMESTAMPn, where n starts with 0 and increments by one for each transaction.
February 2007
41
Back-Office Administration
Viewing Details of a Single Transaction Using GetTransactionDetails
Vi e w i n g D e ta i l s o f a S i n g l e Tr a n s a c t i o n U s i n g G e t Tr a n s a c t i o n D e ta i l s
To view all details about a single transaction, use GetTransactionDetails.
EXAMPLE 5.8 Viewing A Transactions Details Request [requiredSecurityParameters]&METHOD=GetTransactionDetails &TRANSACTIONID=3B288546P5019992D [successResponseFields]&RECEIVERBUSINESS=Jims+Hardware
&RECEIVEREMAIL=jim@hardwareplace.com&RECEIVERID=WNSJNN89XVWFA &PAYERID=B3KS3VFYNG9SN&PAYERSTATUS=unverified&FIRSTNAME=James& LASTNAME=Biguy&COUNTRYCODE=US&SHIPTOSTATE=&ADDRESSID=PayPal&ADDRESSSTATUS=None &TRANSACTIONID=3B288546P5019992D&RECEIPTID=3596-6202-14612615 &TRANSACTIONTYPE=webaccept&PAYMENTTYPE=instant& ORDERTIME=2006-08-15T17:00:00Z&AMT=127.87&CURRENCYCODE=USD&FEEAMT=4.01 &TAXAMT=0.00&PENDINGREASON=None&REASONCODE=None&SALESTAX=0.00&L_QTY0=1
Response
42
February 2007
A
Parameters
The request parameter string follows the query component syntax defined in Uniform Resource Identifier (URI): Generic Syntax. Parameter names and their values can be upper- or lowercase. We show parameter names in uppercase for clarity. All values must be URL-encoded.
Multi-Value Fields
Fields that accept multiple values have names like this:
L_FIELDNAMEn
where L_ is literal, FIELDNAME is the name of the parameter, and n is an index number, starting at 0 and incremented by one for each value of the field. Index numbers must be sequential. For example, if an order contains multiple items, you can add an item cost for each item using the L_AMTn parameter:
L_AMT0=4.95&L_AMT1=6.72&L_AMT2=7.95
February 2007
43
DoDirectPayment
DoDirectPayment Request
DoDirectPayment Parameters Description Name of the API: DoDirectPayment How you want to obtain payment: Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. Sale indicates that this is a final sale for which you are requesting payment. Character length and limit: Up to 13 single-byte alphabetic characters IP address of the payers browser.
I M P O R T A N T : PayPal records this IP addresses as a means to detect
PAYMENTACTION
IPADDRESS
Yes
possible fraud. Character length and limitations: 15 single-byte characters, including periods, for example: 255.255.255.25. Allowable values: any valid Internet Protocol address.
44
February 2007
Required? Yes
CREDITCARDTYPE
Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. Allowable values: Visa MasterCard Discover Amex Switch Solo
I M P O R T A N T : If the credit card type is Switch or Solo, the value of
Yes
PAYMENTACTION must be Authorization and the CURRENCYCODE must be GBP. In addition, either STARTDATE or ISSUENUMBER must be specified. ACCT Credit card number Character length and limitations: numeric characters only. No spaces or punctutation. Must conform with modulo and length required by each credit card type. Credit card expiration date. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero. Payers first name. Character length and limitations: 25 single-byte characters Payers last name. Character length and limitations: 25 single-byte characters First street address. Character length and limitations: 100 single-byte characters Name of city. Character length and limitations: 40 single-byte characters State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see State and Province Abbreviations on page 49. Yes
EXPDATE
Yes
Yes Yes No No No
February 2007
45
Required? No
ZIP NOTIFYURL
No No
from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters CURRENCYCODE A three-character currency code. Default: USD. This parameter accepts only the following currencies: AUD Australian Dollar CAD Canadian Dollar EUR Euro GBP Pound Sterling JPY Japanese Yen USD U.S. Dollar
Sum of cost of all items in this order.
No
ITEMAMT
No
Limitations: The value must be a positive number and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
N O T E : ITEMAMT is required if you specify a value for L_AMTn.
SHIPPINGAMT
No
Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
N O T E : If you specify a value for SHIPPINGAMT, you must also specify a
No
Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
N O T E : If you specify a value for HANDLINGAMT, you must specify a value
for ITEMAMT.
46
February 2007
Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
DESC CUSTOM INVNUM BUTTONSOURCE Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters A free-form field for your own use. Character length and limitations: 256 single-byte alphanumeric characters Your own invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters An identification code for use by third-party applications to identify transactions. Character length and limitations: 32 single-byte alphanumeric characters Your URL for receiving Instant Payment Notification (IPN) about this transaction.
N O T E : If you do not specify this URL in the request, the notification URL
No No No No
NOTIFYURL
No
from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters L_NAMEn Item name. Character length and limitations: 127 single-byte characters These parameters should be ordered sequentially beginning with 0, for example, L_NAME0, L_NAME1, and so forth. L_NUMBERn Item number. Character length and limitations: 127 single-byte characters These parameters should be ordered sequentially beginning with 0, for example, L_NUMBER0, L_NUMBER1, and so forth. L_QTYn Item quantity. Character length and limitations: Any positive integer These parameters should be ordered sequentially beginning with 0, for example, L_QTY0, L_QTY1, and so forth. No No No
February 2007
47
Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
These parameters should be ordered sequentially beginning with 0, for example, L_TAXAMT0, L_TAXAMT1, and so forth. L_AMTn Cost of item No
Limitations: Value can be positive, negative or zero and must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
These parameters should be ordered sequentially beginning with 0, for example, L_AMT0, L_AMT1, and so forth. If you specify a value for L_AMTn, you must specify a value for ITEMAMT. CVV2 Card Verification Value, version 2.
N O T E : Your Merchant Account settings determine whether this field is
See description.
required. Contact your PayPal Account Manager for more information. Character length for Visa, MasterCard, and Discover: exactly three digits. Character length for American Express: exactly four digits.
I M P O R T A N T : To comply with credit card processing regulations, once a
transaction has been completed, you must not store the value of CVV2. STARTDATE Month and year that Switch or Solo card was issued. Format: MMYYYY Character length and limitations: Six single-byte numeric characters, including leading zero. Issue number of Switch or Solo card. Character length: two numeric digits maximum. Email address of payer. Character length and limitations: 127 single-byte characters Second street address. Character length and limitations: 100 single-byte characters Phone number. Character length and limit: 20 single-byte characters No
No No No No
48
February 2007
Required? No
fields are required. TABLE A.3 Parameter SHIPTONAME SHIPTOSTREET SHIPTOCITY SHIPTOSTATE Ship to Address (Optional) Description Persons name associated with this address. Character length and limitations: 32 single-byte characters First street address. Character length and limitations: 100 single-byte characters Name of city. Character length and limitations: 40 single-byte characters State or province. Character length and limitations: 40 single-byte characters For state or province abbreviations, see State and Province Abbreviations on page 49. U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters Country code. Character limit: Two single-byte characters For the list of country codes, see Appendix F, Country Codes. Second street address. Character length and limitations: 100 single-byte characters Phone number. Character length and limit: 20 single-byte characters Required? Yes Yes Yes Yes
SHIPTOZIP SHIPTOCOUNTRY
Yes Yes
SHIPTOSTREET2 SHIPTOPHONENUM
No No
The following table contains abbreviations for Canadian provinces and U.S. states. Enter these values in STATE or SHIPTOSTATE parameter.
TABLE A.1 Abbreviations for Canadian Provinces and U.S. States Canadian Province or U.S. State Alberta British Columbia Abbreviation AB BC
February 2007
49
50
February 2007
February 2007
51
DoDirectPayment Response
TABLE A.4 AVS Code A B C D AVS Response Codes Matched Details Address only (no ZIP) Address only (no ZIP) None Address and Postal Code
52
February 2007
Meaning Not allowed for MOTO (Internet/Phone) transactions UK-specific X Global Unavailable International Unavailable No Postal (International Z) Retry Service not Supported Unavailable Whole ZIP Exact match Yes ZIP Error
CVV2 Response Codes Matched Details CVV2 None Not applicable Not applicable Not applicable Not applicable Not applicable
Meaning Match No match Not Processed Service not Supported Unavailable No response Error
February 2007
53
Express Checkout
SetExpressCheckout Request
SetExpressCheckout Request Parameters Description Name of the API: SetExpressCheckout URL to which the customers browser is returned after choosing to pay with PayPal.
N O T E : PayPal recommends that the value be the final review page on
which the customer confirms the order and payment. Character length and limitations: no limit. CANCELURL URL to which the customer is returned if he does not approve the use of PayPal to pay you.
N O T E : PayPal recommends that the value be the original page on which
Yes
the customer chose to pay with PayPal. Character length and limitations: no limit AMT The total cost of the order to the customer. If shipping cost and tax charges are known, include them in this value; if not, this value should be the current sub-total of the order.
N O T E : Limitations: Must not exceed $10,000 USD in any currency. No
Yes
currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). CURRENCYCODE MAXAMT A three-character currency code for one of the currencies listed in PayPalSupported Transactional Currencies. Default: USD. The expected maximum total amount of the complete order, including shipping cost and tax charges.
N O T E : Limitations: Must not exceed $10,000 USD in any currency.
No No
No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
54
February 2007
Required No
request and then change this value to Authorization on the final API DoExpressCheckoutPayment request. Character length and limit: Up to 13 single-byte alphabetic characters Allowable Values: Authorization Order Sale Default: The transaction resulting from DoExpressCheckoutPayment request will be a final sale.. EMAIL Email address of the buyer as entered during checkout. PayPal uses this value to pre-fill the PayPal membership sign-up portion of the PayPal login page. Character length and limit: 127 single-byte alphanumeric characters Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters A free-form field for your own use, such as a tracking number or other value you want PayPal to return on GetExpressCheckoutDetails response and DoExpressCheckoutPayment response. Character length and limitations: 256 single-byte alphanumeric characters Your own unique invoice or tracking number. PayPal returns this value to you on DoExpressCheckoutPayment response. Character length and limitations: 127 single-byte alphanumeric characters The value 1 indicates that you require that the customers shipping address on file with PayPal be a confirmed address.
N O T E : Setting this field overrides the setting you have specified in your
No
DESC CUSTOM
No No
INVNUM
No
REQCONFIRMSHIPPI NG
No
Merchant Account Profile. Character length and limitations: One single-byte numeric character. Allowable values: 0, 1 Default: 0
February 2007
55
Required No
ADDROVERRIDE
No
customer to edit that address. Allowable values: 0, 1 Default: 0 TOKEN A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout.
N O T E : The token expires after three hours.
No
If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. Character length and limitations: 20 single-byte characters Allowable values: See the description of TOKEN in Table A.8, SetExpressCheckout Response Fields. LOCALECODE Locale of pages displayed by PayPal during Express Checkout. Character length and limitations: Any two-character country code. The following two-character country codes are supported by PayPal: AU DE FR IT GB ES US Any other value will default to US.
N O T E : For the list of country codes, see Appendix
No
F, Country Codes.
No
PAGESTYLE
Sets the Custom Payment Page Style for payment pages associated with this button/link. This value corresponds to the HTML variable page_style for customizing payment pages. The value is the same as the Page Style Name you chose when adding or editing the page style from the Profile subtab of the My Account tab of your PayPal account. Character length and limitations: 30 single-byte alphabetic characters.
56
February 2007
Required No
HDRBORDERCOLOR
No
HDRBACKCOLOR
No
PAYFLOWCOLOR
No
Shipping Address
No
fields are required. TABLE A.7 Parameter SHIPTONAME SHIPTOSTREET SHIPTOCITY SHIPTOSTATE SHIPTOCOUNTRY Ship to Address (Optional) Description Persons name associated with this shipping address. Character length and limitations: 32 single-byte characters First street address. Character length and limitations: 100 single-byte characters Name of city. Character length and limitations: 40 single-byte characters State or province. Character length and limitations: 40 single-byte characters Country code. Character limit: Two single-byte characters. For the list of country codes, see Appendix F, Country Codes. U.S. Zip code or other country-specific postal code. Character length and limitations: 20 single-byte characters Required Yes Yes Yes Yes Yes
SHIPTOZIP
Yes
February 2007
57
SetExpressCheckout Response
SetExpressCheckout Response Fields Description A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout.
N O T E : The token expires after three hours.
If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request. Character length and limitations: 20 single-byte characters Redirecting the Customers 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 customers browser to it:
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout& token=value_from_SetExpressCheckoutResponse
For redirecting the customers browser to the PayPal login page, PayPal recommends that you use the HTTPS response 302 Object Moved with the URL above as the value of the Location header in the HTTPS response. Ensure that you use an SSL-enabled server to prevent browser warnings about a mix of secure and insecure graphics.
GetExpressCheckoutDetails Request
58
February 2007
GetExpressCheckoutDetails Response
TABLE A.10 GetExpressCheckoutDetails Response Fields Field TOKEN Description The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations: 20 single-byte characters Possible values: See the description of TOKEN in Table A.8, SetExpressCheckout Response Fields. Email address of payer. Character length and limitations: 127 single-byte characters Unique PayPal customer account number. Character length and limitations:17 single-byte characters maximum. Status of payer. Character length and limitations: 10 single-byte alphabetic characters. Possible values: verified, unverified Payers salutation. Character length and limitations: 20 single-byte characters Payers first name. Character length and limitations: 25 single-byte characters Payers middle name. Character length and limitations: 25 single-byte characters Payers last name. Character length and limitations: 25 single-byte characters Payers suffix. Character length and limitations: 12 single-byte characters Payers country of residence in the form of ISO standard 3166 two-character country codes. Character length and limitations: Two single-byte characters For the list of country codes, see Appendix F, Country Codes.
February 2007
59
INVNUM
PHONENUM
account profile settings require that the buyer enter one. Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers) or +XXX XXXXXXXX (for international numbers)
DoExpressCheckoutPayment Request
Request to obtain payment with PayPal Express Checkout.
IMPO RTANT: PayPal
requires that a merchant using Express Checkout display to the customer the same amount that the merchant sends to PayPal in the AMT parameter with the DoExpressCheckoutPayment request API.
60
February 2007
TABLE A.11 DoExpressCheckoutPayment Parameters Parameter METHOD TOKEN Description Name of the API: DoExpressCheckoutPayment The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations: 20 single-byte characters How you want to obtain payment: Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. Order indicates that this payment is an order authorization subject to settlement with PayPal Authorization & Capture. Sale indicates that this is a final sale for which you are requesting payment.
N O T E : You cannot set this value to Sale on SetExpressCheckout
PAYMENTACTION
Yes
request and then change this value to Authorization on the final API DoExpressCheckoutPayment request. Character length and limit: Up to 13 single-byte alphabetic characters Allowable Values: Authorization Order Sale Default: The transaction resulting from DoExpressCheckoutPayment request will be a final sale.. PAYERID Encrypted PayPal customer account identification number as returned by GetExpressCheckoutDetails response. Character length and limitations: 127 single-byte characters. Total of order, including shipping, handling, and tax.
N O T E : Limitations: Must not exceed $10,000 USD in any currency.
Yes
AMT
Yes
No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters A free-form field for your own use. Character length and limitations: 256 single-byte alphanumeric characters Your own invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters
No No No
February 2007
61
Required? No
NOTIFYURL
No
from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters ITEMAMT Sum of cost of all items in this order. No
Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
SHIPPINGAMT Total shipping costs for this order.
N O T E : Character length and limitations: Must not exceed $10,000 USD in
No
any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. HANDLINGAMT Total handling costs for this order.
N O T E : Character length and limitations: Must not exceed $10,000 USD in
No
any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. TAXAMT Sum of tax for all items in this order.
N O T E : Character length and limitations: Must not exceed $10,000 USD in
No
any currency. No currency symbol. Regardless of currency, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Equivalent to nine characters maximum for USD. CURRENCYCODE L_NAMEn A three-character currency code for one of the currencies listed in PayPalSupported Transactional Currencies. Default: USD. Item name. Character length and limitations: 127 single-byte characters These parameters should be ordered sequentially beginning with 0, for example, L_NAME0, L_NAME1, and so forth. No No
62
February 2007
Required? No
No
No
No
No
fields are required. TABLE A.12 Optional Ship to Address Parameter SHIPTONAME SHIPTOSTREET SHIPTOCITY Description Persons name associated with this address. Character length and limitations: 32 single-byte characters First street address. Character length and limitations: 100 single-byte characters Name of city. Character length and limitations: 40 single-byte characters Required? Yes Yes Yes
February 2007
63
Yes No No
DoExpressCheckoutPayment Response
TABLE A.13 DoExpressCheckout Payment Response Fields Field TOKEN Description The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request. Character length and limitations:20 single-byte characters Allowable values: See the description of TOKEN in Table A.8, SetExpressCheckout Response Fields. Unique transaction ID of the payment.
N O T E : If the PaymentAction of the request was Authorization or
TRANSACTIONID
Order, this value is your AuthorizationID for use with the Authorization & Capture APIs. Character length and limitations:19 single-byte characters Possible values: Transaction specific TRANSACTIONTYPE The type of transaction Character length and limitations:15 single-byte characters Possible values: cart express-checkout
64
February 2007
ORDERTIME AMT
Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
Possible Values: Transaction specific CURRENCYCODE FEEAMT A three-character currency code for one of the currencies listed in PayPaySupported Transactional Currencies. Default: USD. PayPal fee amount charged for the transaction
Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
Possible values: Transaction specific SETTLEAMT TAXAMT Amount deposited in your PayPal account after a currency conversion. Possible values: Transaction specific Tax charged on the transaction.
Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol. Regardless of currency, decimal separator is a period (.), and the optional thousands separator is a comma (,). Equivalent to nine characters maximum for USD.
Possible values: Transaction specific EXCHANGERATE Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency. If the customer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the customers account. Character length and limitations: a decimal that does not exceed 17 characters, including decimal point Possible values: Transaction specific
February 2007
65
PENDINGREASON
REASONCODE
66
February 2007
DoCapture
TABLE A.14 DoCapture Parameters Parameter METHOD AUTHORIZATIONID Description Name of API: DoCapture The authorization identification number of the payment you want to capture. This is the transaction id returned from DoExpressCheckoutPayment or DoDirectPayment. Character length and limits: 19 single-byte characters maximum. Amount to capture. Required? Yes Yes
AMT
Yes
Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
CURRENCYCODE COMPLETETYPE A three-character currency code for one of the currencies listed in PayPaySupported Transactional Currencies. Default: USD. The value Complete indicates that this the last capture you intend to make. The value NotComplete indicates that you intend to make additional captures.
N O T E : If Complete, any remaining amount of the original authorized
No Yes
transaction is automatically voided and all remaining open authorizations are voided. Character length and limits: 12 single-byte alphanumeric characters INVNUM Your invoice number or other identification number that is displayed to the merchant and customer in his transaction history.
N O T E : This value on DoCapture will overwrite a value previously set on
No
DoAuthorization.
N O T E : The value is recorded only if the authorization you are capturing is
an order authorization, not a basic authorization. Character length and limits: 127 single-byte alphanumeric characters NOTE An informational note about this settlement that is displayed to the payer in email and in his transaction history. No
February 2007
67
TRANSACTIONID
RECEIPTID
TRANSACTIONTYPE
PAYMENTTYPE
The final amount charged, including any shipping and taxes from your Merchant Profile. PayPal fee amount charged for the transaction Amount deposited in your PayPal account if there is a currency conversion. Tax charged on the transaction, if any
68
February 2007
DoAuthorization
TABLE A.16 DoAuthorization Parameters Parameter METHOD Description Name of the API: DoAuthorization Required? Yes
February 2007
69
Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
TRANSACTIONENTIT Y Type of transaction to authorize. The only allowable value is Order, which means that the transaction represents a customer order that can be fulfilled over 29 days. A three-character currency code for one of the currencies listed in PayPaySupported Transactional Currencies. Default: USD. No
CURRENCYCODE
No
TABLE A.17 DoAuthorization Response Fields Field TRANSACTIONID Description An authorization identification number. Character length and limits: 19 single-byte characters
AMT
DoVoid
TABLE A.18 DoVoid Request Parameters Parameter METHOD Description Name of API: DoVoid Required? Yes
70
February 2007
Required? Yes
use the ID from the original authorization, and not the reauthorization. Character length and limits: 19 single-byte characters NOTE An informational note about this void that is displayed to the payer in email and in his transaction history. Character length and limits: 255 single-byte characters No
TABLE A.19 DoVoid Response Fields Field AUTHORIZATIONID Description The authorization identification number you specified in the request. Character length and limits: 19 single-byte characters
DoReauthorization
TABLE A.20 DoReauthorization Request Parameters Parameter METHOD AUTHORIZATIONID Description Name of API: DoReauthorization The value of a previously authorized transaction identification number returned by PayPal. Character length and limits: 19 single-byte characters maximum Amount to reauthorize. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). A three-character currency code for one of the currencies listed in PayPaySupported Transactional Currencies. Default: USD. Required? Yes Yes
AMT
Yes
CURRENCYCODE
No
February 2007
71
RefundTransaction
TABLE A.22 RefundTransaction Request Parameters Parameter METHOD TRANSACTIONID REFUNDTYPE Description Name of API call: RefundTransaction Unique identifier of a transaction Character length and limitations: 17 single-byte alphanumeric characters Type of refund you are making Other Full Partial Refund amount. Amount is required if RefundType is Partial.
N O T E : If RefundType is Full, do not set Amount.
AMT
No
NOTE
Custom memo about the refund. Character length and limitations: 255 single-byte alphanumeric characters
No
TABLE A.23 DoRefund Response Fields Field REFUNDTRANSACTIONID NETREFUNDAMT FEEREFUNDAMT GROSSREFUNDAMT Description Unique transaction ID of the refund. Character length and limitations:17 single-byte characters Amount subtracted from PayPal balance of original recipient of payment to make this refund Transaction fee refunded to original recipient of payment Amount of money refunded to original payer
72
February 2007
TransactionSearch
With TransactionSearch you must always set the StartDate field. Some other behavior: Setting TransactionID overrides all other fields (even the required StartDate field). The effect of setting other elements is additive or can alter the search criteria. TransactionSearch returns up to 100 matches. Partial matches are displayed. For example, setting the TransactionSearchRequest FirstName to Jess returns results such as Jessica and Jesse. The most important returned element is TransactionID, which you can pass to GetTransactionDetails in order to retrieve all available information about a specific transaction.
TABLE A.24 TransactionSearch Parameters Parameter METHOD STARTDATE ENDDATE EMAIL RECEIVER RECEIPTID TRANSACTIONID Description Name of API call: TransactionSearch The earliest transaction date at which to start the search.
N O T E : No wildcards are allowed. The value must be in UTC/GMT format.
The latest transaction date to be included in the search Search by the buyers email address Character length and limitations: 127 single-byte alphanumeric characters Search by the receivers email address. If the merchant account has only one email, this is the primary email. Can also be a non-primary email. Search by the PayPal Account Optional receipt ID Search by the transaction ID.
N O T E : The returned results are from the merchants transaction records.
No No No No No
Character length and limitations: 19 single-byte characters maximum INVNUM Search by invoice identification key, as set by you for the original transaction. This field searches the records for items sold by the merchant, not the items purchased.
N O T E : No wildcards are allowed.
No
Character length and limitations: 127 single-byte characters maximum ACCT Search by credit card number, as set by you for the original transaction. This field searches the records for items sold by the merchant, not the items purchased.
N O T E : No wildcards are allowed.
No
Character length and limitations: Must be at least 11 and no more than 25 single-byte numeric characters maximum. Special punctuation, such as dashes or spaces, is ignored.
February 2007
73
Required No No No No No No No
with this field. You cannot search for bank transfer withdrawals, for example. All: all transaction classifications Sent: only payments sent Received: only payments received MassPay: only mass payments MoneyRequest: only money requests FundsAdded: only funds added to balance FundsWithdrawn: only funds withdrawn from balance Referral: only transactions involving referrals Fee: only transactions involving fees Subscription: only transactions involving subscriptions Dividend: only transactions involving dividends Billpay: only transactions involving BillPay Transactions Refund: only transactions involving funds CurrencyConversions: only transactions involving currency conversions BalanceTransfer: only transactions involving balance transfers Reversal: only transactions involving BillPay reversals Shipping: only transactions involving UPS shipping fees BalanceAffecting: only transactions that affect the account balance ECheck: only transactions involving eCheck AMT Search by transaction amount No
74
February 2007
STATUS
No
TABLE A.25 TransactionSearch Response Fields Field L_TIMESTAMPn Description The date and time (in UTC/GMT format) the transaction occurred These parameters should be ordered sequentially beginning with 0, for example, L_TIMESTAMP0, L_TIMESTAMP1, and so forth. L_TIMEZONEn The time zone of the transaction These parameters should be ordered sequentially beginning with 0, for example, L_TIMEZONE0, L_TIMEZONE1, and so forth. L_TYPEn The type of the transaction These parameters should be ordered sequentially beginning with 0, for example, L_TYPE0, L_TYPE1, and so forth. L_EMAILn The email address of either the payer or the payment recipient (the payee). If the payment amount is positive, this field is the recipient of the funds. If the payment is negative, this field is the paying customer. These parameters should be ordered sequentially beginning with 0, for example, L_EMAIL0, L_EMAIL1, and so forth.
February 2007
75
GetTransactionDetails
TABLE A.26 GetTransactionDetails Parameters Parameter METHOD TRANSACTIONID Description Name of the API: GetTransactionDetails Unique identifier of a transaction.
N O T E : The details for some kinds of transactions cannot be retrieved with
GetTransactionDetails. You cannot obtain details of bank transfer withdrawals, for example. Character length and limitations: 17 single-byte alphanumeric characters
76
February 2007
RECEIVEREMAIL
February 2007
77
SHIPTOCITY SHIPTOCOUNTRYNAM E SHIPTONAME SHIPTOPHONENUM SHIPTOZIP SHIPTOSTATE SHIPTOSTREET SHIPTOSTREET2 PARENTTRANSACTIO NID
TRANSACTIONID RECEIPTID
78
February 2007
TAXAMT EXCHANGERATE
February 2007
79
PENDINGREASON
Pending. The reason the payment is pending: none: No pending reason address: The payment is pending because your customer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile. echeck: The payment is pending because it was made by an eCheck that has not yet cleared. intl: The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview. multi-currency: You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment. verify: The payment is pending because you are not yet verified. You must verify your account before you can accept this payment. other: The payment is pending for a reason other than those listed above. For more information, contact PayPal Customer Service.
80
February 2007
February 2007
81
82
February 2007
Mass Payment
TABLE A.28 MassPay Parameters Parameter METHOD RECEIVERTYPE Description Name of the API: MassPay Indicates how you identify the recipients of payments in all the individual mass payment items: either by EmailAddress (L_EMAILn in the individual item) or by UserID (L_RECEIVERID_n in the individual item). Payment amount. A three-character currency code for one of the currencies listed in PayPaySupported Transactional Currencies. Default: USD. Email address of recipient.
N O T E : You must specify either L_EMAILn or L_RECEIVERIDn, but you
must not mix them. Use only one or the other, but not both, in a single request. Character length and limitations: 127 single-byte characters maximum. These parameters should be ordered sequentially beginning with 0, for example, L_EMAIL0, L_EMAIL1, and so forth. L_RECEIVERIDn Unique PayPal customer account number. This value corresponds to the value of PAYERID returned by GetTransactionDetails. These parameters should be ordered sequentially beginning with 0, for example, L_RECEIVERID0, L_RECEIVERID1, and so forth. L_UNIQUEIDn Transaction-specific identification number for tracking in an accounting system. Character length and limitations: 30 single-byte characters. No whitespace allowed. These parameters should be ordered sequentially beginning with 0, for example, L_UNIQUEID0, L_UNIQUEID1, and so forth. L_NOTEn Custom note for each recipient. Character length and limitations: 4,000 single-byte alphanumeric characters These parameters should be ordered sequentially beginning with 0, for example, L_NOTE0, L_NOTE1, and so forth. EMAILSUBJECT The subject line of the email that PayPal sends when the transaction is completed. The subject line is the same for all recipients. Character length and limitations: 255 single-byte alphanumeric characters
No
No
February 2007
83
84
February 2007
Validation Errors
TABLE B.1 Validation Errors Error Code 81000 81001 81002 81003 81004 81100 81101 81102 81103 81104 81105 Short Message Missing Parameter Invalid Parameter Unspecified Method Unspecified Method Unspecified Method Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Long Message Required Parameter Missing : Unable to identify parameter A Parameter is Invalid : Unable to identify parameter Method Specified is not Supported No Method Specified No Request Received OrderTotal (Amt) : Required parameter missing MaxAmt : Required parameter missing ReturnURL: Required parameter missing NotifyURL : Required parameter missing CancelURL : Required parameter missing ShipToStreet : Required parameter missing
Developers Guide
February 2007
85
86
February 2007
Developers Guide
Developers Guide
February 2007
87
88
February 2007
Developers Guide
General API Errors Long Message Username/Password is incorrect Correcting This Error This error can be caused by an incorrect API username, an incorrect API password, or an invalid API signature. Make sure that all three of these values are correct. For your security, PayPal does not report exactly which of these three values might be in error.
10002
Authentication /Authorization Failed Authentication /Authorization Failed Internal Error Authentication /Authorization Failed Authentication /Authorization Failed Authentication /Authorization Failed Authentication /Authorization Failed Restricted account Authentication /Authorization Failed
You do not have permissions to make this API call Account is locked or inactive
10002
10002 10002
10002
10002
10002
10002 10002
Developers Guide
February 2007
89
Short Message Authentication /Authorization Failed Authentication /Authorization Failed Restricted account
10002
10002
Account is restricted
TABLE B.2 Direct Payment API Errors Error Code 10500 Short Message Invalid Configuration Invalid Configuration Invalid Data Long Message This transaction cannot be processed due to an invalid merchant configuration. This transaction cannot be processed due to an invalid merchant configuration. This transaction cannot be processed. Please use a valid credit card. This transaction cannot be processed. Please enter a valid Credit Card Verification Number. This transaction cannot be processed. This transaction cannot be processed. Please contact PayPal Customer Service. This transaction cannot be processed. Please enter a valid credit card expiration date. Corrective Action Occurs when you have not agreed to the billing agreement. Occurs when the billing agreement is disabled or inactive. The credit card used is expired.
10501
10502
10504
Invalid Data
The CVV provide is invalid. The CVV is between 3-4 digits long. The transaction was refused because the AVS response returned the value of N, and the merchant account is not able to accept such transactions. Your PayPal account is restricted - contact PayPal for more information. The expiration date must be a two-digit month and four-digit year.
10505
10507
10508
90
February 2007
Developers Guide
10513
Invalid Data
10523 10525
None - this is a PayPal internal error. The merchant entered a amount of zero.
10526
Invalid Data
10527
Invalid Data
10534
The credit card entered is currently restricted by PayPal. Contact PayPal for more information. The credit card entered is invalid.
10535
Developers Guide
February 2007
91
10537
Filter Decline
10538
Filter Decline
10539 10540
This transaction cannot be processed. The transaction cannot be processed due to an invalid address. This transaction cannot be processed. Please enter a valid credit card number and type. This transaction cannot be processed. Please enter a valid email address. This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. The merchant's accouht is not able to process transactions.
10541
10542
10544 10545
Gateway Decline Gateway Decline Gateway Decline Internal Error Invalid Configuration
10546
10547 10548
92
February 2007
Developers Guide
10550 10552
10553 10554
10555
Filter Decline
10556
Filter Decline
10561
Invalid Data
There's an error with this transaction. Please enter complete billing address. This transaction cannot be processed. Please enter a valid credit card expiration year. This transaction cannot be processed. Please enter a valid credit card expiration month. This transaction cannot be processed. The merchant country is not supported. There was a problem processing this transaction.
10562
Invalid Data
10563
Invalid Data
10564 10565
Developers Guide
February 2007
93
10567
10701
Invalid Data
10702
Invalid Data
10703
Invalid Data
10704
Invalid Data
10705
Invalid Data
10706
Invalid Data
10707
Invalid Data
10708
Invalid Data
10709
Invalid Data
10709
Invalid Data
10710
Invalid Data
94
February 2007
Developers Guide
10711
Invalid Data
10712
Invalid Data
10713
Invalid Data
10713
Invalid Data
10714
Invalid Data
10715
Invalid Data
10716
Invalid Data
10717
Invalid Data
10718
Invalid Data
10719
Invalid Data
10720
Invalid Data
Developers Guide
February 2007
95
10722
Invalid Data
10723
Invalid Data
10724
Invalid Data
10725
Invalid Data
10726
Invalid Data
10726
Invalid Data
10727
Invalid Data
10727
Invalid Data
10728
Invalid Data
10728
Invalid Data
10729
Invalid Data
96
February 2007
Developers Guide
10731
Invalid Data
10731
Invalid Data
10732
Invalid Data
10733
Invalid Data
10734
Invalid Data
10735
Invalid Data
10736
Invalid Data
10744
Invalid Data
10745
Invalid Data
10746
Invalid Data
Developers Guide
February 2007
97
10748
Invalid Data
10750
Invalid Data
10751
Invalid Data
10752
10754 10755
10756
Gateway Decline
10758
The API username or password is incorrect for this merchant. The transaction was declined by PayPal. Contact PayPal for more information. The merchant's country of residence listed in their PayPal account is not currently supported to allow Direct Payment transactions. The transaction was declined because PayPal is currently processing a transaction by the same buyer for the same amount. Can occur when a buyer submits multiple, identical transactions in quick succession.
10759
10760
10761
Gateway Decline
98
February 2007
Developers Guide
15002 15003
15004
This transaction cannot be processed. Please enter a valid Credit Card Verification Number. This transaction cannot be processed. This transaction cannot be processed. Please enter a valid credit card number and type. This transaction cannot be processed. Please use a valid credit card.
15005
15006
15007
TABLE B.3 SetExpressCheckout API Errors Error Code 10001 Short Message ButtonSource value truncated. Long Message The transaction could not be loaded Correcting This Error...
Developers Guide
February 2007
99
10004
10007 10102
You do not have permissions to make this API call PaymentAction of Order is temporarily unavailable. Please try later or use other PaymentAction. This merchant account is not permitted to set PaymentAction to Authorization. Please contact Customer Service. ReturnURL is missing.
10402
10404
100
February 2007
Developers Guide
10407
10409
Express Checkout token was issued for a merchant account other than yours.
10410
Invalid token.
Developers Guide
February 2007
101
102
February 2007
Developers Guide
10415
Transaction refused because of an invalid argument. See additional error messages for details.
10425
Express Checkout has been disabled for this merchant. Transaction refused because of an invalid argument. See additional error messages for details.
Express Checkout has been disabled for this merchant. Please contact Customer Service.
10432
Developers Guide
February 2007
103
10434
10436
10437
10438
104
February 2007
Developers Guide
10440
10471
10472
CancelURL is invalid.
10537
The transaction was refused because the country was prohibited as a result of your Country Monitor Risk Control Settings. The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk Control Settings.
10538
Developers Guide
February 2007
105
10725
There was an error in the Shipping Address Country field The field Shipping Address1 is required
10727
10728
10729
10730
The field Shipping Address Postal Code is required The field Shipping Address Country is required A match of the Shipping Address City, State, and Postal Code failed.
10731
10736
TABLE B.4 GetExpressCheckoutDetails API Errors Error Code 10001 10001 Short Message Internal Error Internal Error Long Message Internal Error Transaction failed due to internal error Correcting This Error...
106
February 2007
Developers Guide
10001
10004
10004
10004
You can not get the details for this type of transaction The transaction could not be loaded
10004
10004
Developers Guide
February 2007
107
10409
Express Checkout token was issued for a merchant account other than yours. Invalid token. This Express Checkout session has expired. Token value is no longer valid.
10410 10411
TABLE B.5 DoExpressCheckoutPayment API Errors Error Code 10001 10001 Short Message Internal Error Internal Error Long Message Transaction failed due to internal error Warning an internal error has occurred. The transaction id may not be correct The transaction could not be loaded Internal Error Correcting This Error...
10001
10001
108
February 2007
Developers Guide
10004
10007 10406
You do not have permissions to make this API call The PayerID value is invalid.
10408
10409
Express Checkout token was issued for a merchant account other than yours. Invalid token. This Express Checkout session has expired. Token value is no longer valid. Payment has already been made for this InvoiceID.
10410 10411
10412
Developers Guide
February 2007
109
10414
Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details.
10415
10416
You have exceeded the maximum number of payment attempts for this token.
You can send a maximum of 10 DoExpressCheckoutPayment API calls for any single token value, after which the token becomes invalid.
110
February 2007
Developers Guide
10418
Transaction refused because of an invalid argument. See additional error messages for details. Express Checkout PayerID is missing. Transaction refused because of an invalid argument. See additional error messages for details.
10419
10420
Developers Guide
February 2007
111
10422
10423
Transaction refused because of an invalid argument. See additional error messages for details.
10424
Transaction refused because of an invalid argument. See additional error messages for details.
112
February 2007
Developers Guide
10433
10434
10435
The customer has not yet confirmed payment for this Express Checkout session.
10441
Developers Guide
February 2007
113
10443
10444
10445
This transaction cannot be processed at this time. Please try again later.
10446 10474
A confirmed email is required to make this API call. This transaction cannot be processed. The country code in the shipping address must match the buyers country of residence. The transaction was refused because the country was prohibited as a result of your Country Monitor Risk Control Settings. The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk Control Settings. The buyer selects the country of residence when they sign up for their PayPal account. The country of residence is displayed after the dash in the title on the Account Overview page.
10537
10538
114
February 2007
Developers Guide
10725
There was an error in the Shipping Address Country field The field Shipping Address1 is required The field Shipping Address City is required The field Shipping Address State is required The field Shipping Address Postal Code is required The field Shipping Address Country is required A match of the Shipping Address City, State, and Postal Code failed.
10727
10728
10729
10730
10731
10736
Developers Guide
February 2007
115
TABLE B.6 Authorization & Capture API Error Messages Error Code 10001 10001 10004 10007 10009 10010 Short Message Internal Error Internal Error Internal Error Permission denied Transaction refused Transaction refused because of an invalid argument. See additional error messages for details. Authorization voided. Long Message Internal Error Transaction failed due to internal error Invalid argument You do not have permissions to make this API call Account is locked or inactive Invalid argument Retry the request at a later time or close order. Returned By API Call... Correcting This Error...
10600
Authorization is voided.
DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoVoid
10601
Authorization expired.
10602
Authorization completed.
10603
116
February 2007
Developers Guide
10605 10606
DoAuthorization DoCapture DoAuthorization DoCapture DoReauthorization DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoAuthorization DoCapture DoReauthorization DoCapture
10607
10608
10609
10610
Amount specified exceeds allowable limit. Authorization & Capture feature is not enabled for the merchant. Contact customer service. Maxmimum number of allowable settlements has been reached. No more settlement for the authorization. Currency of capture must be the same as currency of authorization. You can void only the original authorization, not a reauthorization.
Reattempt the request with a lower amount. Contact PayPal Customer Service.
10611
10612
No more settlement.
10613
DoCapture
Ensure that the currencies are the same, and retry the request. Void the authorization.
10614
DoVoid
Developers Guide
February 2007
117
10616
DoReauthorization
10617
Reauthorization is not allowed inside honor period. Transaction has already been voided or expired.
DoReauthorization
Capture the authorization ro reauthorize outside of honor period. Close the orde or authorizationr.
10618
10619
Invoice ID value exceeds maximum allowable length. Order has already been voided, expired or completed. Order has expired. Order is voided. Maximum number of authorization allowed for the order is reached. Duplicate invoice
10620
Order has already been voided, expired or completed. Order has expired.
DoAuthorization DoCapture DoVoid DoAuthorization DoCapture DoVoid DoAuthorization DoCapture DoVoid DoAuthorization DoCapture DoReauthorization DoVoid
10621
10622
Order is voided.
10623
10624
DoAuthorization
118
February 2007
Developers Guide
10626
Transaction refused due to risk model The invoice ID field is not supported for basic authorizations
10627
Transaction refused because of an invalid argument. See additional error messages for details. This transaction cannot be processed at this time. Please try again later. Reauthorizatio n not allowed. Item amount is invalid. This authorization cannot be voided, reauthorized, or captured against.
10628
This transaction cannot be processed at this time. Please try again later.
10629
Reauthorization is not allowed for this type of authorization. Item amount is invalid.
DoReauthorization
Use DoAuthorization to authorize the an order. Check the item amount to ensure that it is not zero or negative.
10630
DoAuthorization DoCapture
11094
This authorization can only be handled through the marketplace which created it. It cannot directly be voided, reauthorized, or captured against.
Developers Guide
February 2007
119
TABLE B.7 RefundTransaction API Errors Error Code 10001 10001 10001 Short Message Internal Error Internal Error ButtonSource value truncated. Internal Error Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Long Message Internal Error Warning an internal error has occurred. The transaction id may not be correct The transaction could not be loaded Correcting This Error...
10001 10004
10004
10004
A transaction id is required
120
February 2007
Developers Guide
10004
10004
A transaction id is required
10004
10004
10007
Developers Guide
February 2007
121
The partial refund amount must be less than or equal to the original transaction amount The partial refund amount must be less than or equal to the remaining amount The partial refund amount is not valid Because a complaint case exists on this transaction, only a refund of the full or full remaining amount of the transaction can be issued You are over the time limit to perform a refund on this transaction Can not do a full refund after a partial refund Account is locked or inactive The partial refund must be the same currency as the original transaction This transaction has already been fully refunded
Transaction refused Transaction refused Transaction refused Transaction refused Transaction refused
122
February 2007
Developers Guide
11001
TransactionSearch API Errors Long Message Internal Error The transaction could not be loaded Start date is a required parameter
Short Message Internal Error ButtonSource value truncated. Transaction refused because of an invalid argument. See additional error messages for details.
Developers Guide
February 2007
123
Short Message Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details.
10004
10004
10004
10004
10004
10004
10004
10004
10004
124
February 2007
Developers Guide
Short Message Transaction refused because of an invalid argument. See additional error messages for details. Permission denied Permission denied Search warning
You do not have permissions to search for this transaction You do not have permissions to make this API call The number of results were truncated. Please change your search parameters if you wish to see all your results.
TABLE B.8 GetTransactionDetails API Errors Error Code 10001 Short Message Internal Error Long Message Internal Error
Developers Guide
February 2007
125
10002 10004
The user account is locked The number of input records is greater than maximum allowed
10004
10004
The note string length exceeds the maximum limit of 4000 characters
10004
126
February 2007
Developers Guide
10004
10004
10004
The amount exceeds the max limit of a single mass pay item ~1
10004
Developers Guide
February 2007
127
10004
10004
You do not have permissions to make this API call The user is not allowed to send money through Mass Pay Account is restricted The user account has unconfirmed email The user account needs to have its sending limit removed in order to make a mass payment. The users international account needs to have its sending limit removed in order to make a mass payment The user account is receive only and therefore cannot send payments out
128
February 2007
Developers Guide
10309
10310 10311
Unable to create payments for masspay Unable to submit payments for masspay
The masspay server has reported errors The masspay input file includes invalid data The input to the masspay server is incorrect. Please make sure that you are using a correctly formatted input. The masspay input file includes invalid Email Internal Error The account does not have sufficient funds to do this masspay The masspay input file includes invalid UserID
Developers Guide
February 2007
129
130
February 2007
Developers Guide
This chapter describes the NVP API Web Samples which access the NVP API directly. This section includes the following topics: Descriptions of the Samples on page 131 Samples Using Classic ASP on page 136 Samples Using PHP on page 136 Samples Using ColdFusion on page 137
specific filenames are shown as filename.ext. For example, DoDirectPayment.ext stands for DoDirectPayment.java, DoDirectPayment.php, and so forth.
DoDirectPayment - Authorization Authorize a credit card for later sale. In the DoDirectPayment request, the PAYMENTACTION parameter is set to Authorization.
Developers Guide
February 2007
131
DoDirectPaymentReceipt.ext
132
February 2007
Developers Guide
ReviewOrder.ext
The code collects transaction parameters from the form displayed by SetExpressCheckout.ext then constructs and sends a SetExpressCheckout request string to the PayPal server. The paymentType variable becomes the PAYMENTACTION parameter of the request string. The RETURNURL parameter is set to this file; this is how ReviewOrder.ext is called twice. On the second pass, the code executes the else statement. On the first pass, the buyer completed the authorization in their PayPal account; now the code gets the payer details by sending a GetExpressCheckoutDetails request to the PayPal server. Then the code calls GetExpressCheckoutDetails.ext.
N O T E : Be sure to check the value of PAYPAL_URL. The buyer
is sent to this URL to authorize payment with their PayPal account. For testing purposes, this should be set to the PayPal sandbox. Called by SetExpressCheckout.ext. Calls GetExpressCheckoutDetails.ext, CallerService.ext, and Display.ext. GetExpressCheckoutDetails.ext This functionality is called after the buyer returns from PayPal and has authorized the payment. Displays the payer details returned by the GetExpressCheckoutDetails response and calls DoExpressCheckoutPayment.ext to complete the payment authorization. Called by ReviewOrder.ext. Calls DoExpressCheckoutPayment.ext and CallerService.ext.
Developers Guide
February 2007
133
TransactionDetails.ext
134
February 2007
Developers Guide
Common Files
The following files are common to the samples.
TABLE C.4 File index.html Default.htm sdk.css CallerService.ext Common Files Description The main web page with links to each sample. Calls DoDirectPayment.ext, SetExpressCheckout.ext, and GetTransactionDetails.html. Cascading Style Sheet (CSS) used by index.html or Default.htm. This is the configuration file for the samples.This file contains the parameters needed to make an API call. The samples come with an API Signature for making API calls to the PayPal sandbox. The API Signature is described in Table C.5, Called by TransactionDetails.ext, ReviewOrder.ext, DoDirectPaymentReceipt.ext, and Display.ext. Display.ext Displays request and response parameters. If there is an error, displays request and error parameters. Called by DoDirectPaymentReceipt.ext, TransactionDetails.ext, and DoExpressCheckoutPayment.ext.
API Signature
The API Signature that comes with the samples belongs to the following user:
TABLE C.5 Details of Sample API Signature
sdk-three_api1.sdk.com QFZCWN5HZM8VBG7Q A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU
IMPO RTANT: You must protect the API Signature values in your implementation. Consider
storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production.
Developers Guide
February 2007
135
Required Software
No additional software is required.
Required Software
The following software is required:
TABLE C.6 Software PHP with CURL extension enabled Apache HTTP Server Required Software Version 4.4.2 or greater 1.3.17 or greater Download Location http://www.php.net/downloads.php http://httpd.apache.org/
You must install and configure PHP with the Apache HTTP Server.
136
February 2007
Developers Guide
Required Software
The following software is required:
TABLE C.7 Standard
ColdFusion
1. Copy the sample folder to your ColdFusion application server web document root, ColdFusionMX7_root_directory\wwwroot.
Developers Guide
February 2007
137
138
February 2007
Developers Guide
This section describes how to use the Java SDK for the NVP API and includes the following topics: Installing the Java SDK on page 139 Profiles on page 141 Sample Applications on page 143
Supported Standards
The PayPal SDK has been verified to work with the following standards.
TABLE D.1 Standard Java Runtime Environment Supported Human Languages Supported Standards Version 1.4.2 or greater
Developers Guide
February 2007
139
refer to the directory in which you choose to extract the SDK as: SDK_root.
Post-installation Set-up
This section details steps you must take before you start using the PayPal SDK.
Adding SDK JAR Files to CLASSPATH
Before developing applications with the Java SDK, be sure to add the SDK JAR files in SDK_root/lib to your CLASSPATH environment variable.
SDK Directories and Optional Configurations
The Java SDK components are organized into different subdirectories, as shown in Table D.3, PayPal SDK for Java: Directories and Contents.
TABLE D.3 Directory cert docs lib licenses samples src tools PayPal SDK for Java: Directories and Contents Descrption PayPal public certificates for Live PayPal and PayPal Sandbox SDK API documentation SDK libraries License files Example code that use the SDK. SDK source code Third-party applications
140
February 2007
Developers Guide
SDK Logging
The PayPal SDK uses log4j public domain logging software. For complete information, see the documentation at http://logging.apache.org/log4j/docs/
Setting Log Levels
responses might appear out of sequence in the log file. Logfile Backup
The default size of the SDK log is 10MB. You can set this size larger or smaller with the value of param name=MaxFileSize in log4j.properties. When the log file reaches its maximum size, a backup file is created and a new logfile begins.
Profiles
Before the SDK can be used, it must know the profile of the user accessing its services. A profile is a collection of information about a merchant or developer who uses the PayPal SDK. An API profile is associated with API Services and includes: A PayPal API username and password. If you are using API Certificates, the path to the API certificate in P12 format and the private key password to that certificate.
Developers Guide
February 2007
141
If you are using API Signatures, the signature string. The optional name of a third-party who authorizes the caller to invoke PayPal APIs on his behalf. This third-party is called a subject The PayPal environment for processing API calls: live or sandbox. An EWP profile is associated with EWP Services includes: The path to the merchants local copy of that public certificate The private key password for that public certificate The path to a merchants private key file for digitally signing data The URL to which the button form POSTs The optional URL of a payment button image. The default is PayPals standard Buy Now button. For more information about how EWP works, see the Website Payments Standard Integration Guide, available at https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_IntegrationGuide.pdf.
EWPProfile interface
142
February 2007
Developers Guide
Profiles class
Sample Application s
The PayPal SDK includes sample applications in the SDK_root/samples directory. Each subdirectory comes with a README file that explains how to set up the application.
TABLE D.6 PayPal SDK for Java: Sample Code in SDK_root/samples Descrption API certificates used by the sample applications JavaScript implementation for Apache Tomcat of the following PayPal APIs: Direct Payment for final sale and for authorization Express Checkout for final sale and for authorization TransactionSearch GetTransactionDetails RefundTransaction DoCapture DoVoid Native Java application to call TransactionSearch, GetTransactionDetails, and DirectPayment
SampleApp
Developers Guide
February 2007
143
storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production.
must protect the API Certificate values in your implementation. Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production.
144
February 2007
Developers Guide
This section describes how to use the ASP.NET SDK for the NVP API and includes the following topics: Installing the ASP.NET SDK on page 145 Profiles on page 149 Sample Applications on page 150
Supported Standards
The PayPal SDK has been verified to work with the following standards.
TABLE E.1 Standard Microsoft .NET Framework Supported Human Languages Supported Standards Version 1.1, Service Pack 1
The following table lists the minimum hardware requirements for using the PayPal SDK in development and test. Production systems might require more capacity, depending on their expected load.
TABLE E.2 Component RAM CPU Minimum System Hardware Requirements Minimum Capacity 256 MB Pentium 1 GHz
Developers Guide
February 2007
145
PayPal SDK requires Service Pack 1 for Microsoft .NET Framework 1.1. You can get Service Pack 1 from the Microsoft web site.
Post-installation Set-up
This section details steps to take before you start using the PayPal SDK.
Referencing the SDK DLLs
Before developing applications with the SDK, be sure to add references in your ASP.NET projects to the SDK dynamic load libraries (DLLs) in SDK_root\bin.
Installing the Samples
The SDK comes with sample applications for your study and use. These samples can be installed in Microsoft Internet Information Server (IIS). For more information about the samples, see Sample Applications on page 150. For more information about installing in IIS, see Installing the Samples in IIS on page 152.
SDK Directories and Optional Configurations
The SDK components are organized into different subdirectories, as shown in Table E.3, PayPal SDK Directories and Contents.
TABLE E.3 Directory bin docs PayPal SDK Directories and Contents Descrption Compiled SDK DLLs Ndoc class documentation and SDK guide samples\ASPNET Example code that use the SDK, in subdirectories
146
February 2007
Developers Guide
First, add a <section name=paypal> tag, as shown below. The section must be enclosed in <configSections> that comes immediately after the top-level <configuration> tag.
<configuration> <configSections> <section name=paypal type=com.paypal.sdk.core.ConfigSectionHandler, paypal_base/> <configSections>
The optional custom settings themselves are in a <paypal> block later in the file:
<paypal> ... custom settings ... </paypal>
SDK Logging
The PayPal SDK uses log4net public domain logging software. For information about log4net, see the log4net documentation at http://logging.apache.org/log4net/release/manual/introduction.html. This section describes SDK logging levels, in which configuration files you set the desired level, and request logging.
Log Levels
The SDK varies the amount of detail it records according to four logging levels.
TABLE E.4 Level ALL ERROR SDK Logging Levels Description Same as DEBUG Log only severe errors
Developers Guide
February 2007
147
responses might appear out of sequence in the log file. Setting SDK Log Levels
To enable logging for your SDK-based web applications, add the following lines inside the <configuration> block of the Web.config file. You can copy these lines from the SDK_root\samples\ASPNET\Web.config file. You might want to change the value of the file element to write log records to a location you prefer. Set the value of the level element to the desired detail described in Table E.4, SDK Logging Levels.
<configSections> <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,log4net"/> </configSections> <log4net> <appender name="PAYPALLOGFILE" type="log4net.Appender.RollingFileAppender"> <file value="logs/paypal.sdk.log" /> <appendToFile value="true" /> <encoding value="UTF-8" /> <rollingStyle value="5" /> <maxSizeRollBackups value="10" /> <maximumFileSize value="10MB" /> <staticLogFileName value="true" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%d{dd MMM yyyy HH:mm:ss} %-5p [%C{1}] %m%n" /> </layout> </appender> <logger name="com.paypal.sdk"> <level value="ALL" /> <appender-ref ref="PAYPALLOGFILE" /> </logger> </log4net>
148
February 2007
Developers Guide
Profiles
Before the SDK can be used, it must know the profile of the user accessing its services. A profile is a collection of information about a merchant or developer who uses the PayPal SDK. An API profile is associated with API Services and includes: A PayPal API username and password. If you are using API Certificates, the path to the API certificate in P12 format and the private key password to that certificate. If you are using API Signatures, the signature string. The optional name of a third-party who authorizes the caller to invoke PayPal APIs on his behalf. This third-party is called a subject. The PayPal environment for processing API calls: live or sandbox. An EWP profile is associated with EWP Services includes: The path to the merchants local copy of that public certificate The private key password for that public certificate The path to a merchants private key file for digitally signing data The URL to which the button form POSTs The optional URL of a payment button image. The default is PayPals standard Buy Now button.
Developers Guide
February 2007
149
For more information about how EWP works, see the Website Payments Standard Integration Guide, available at https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_IntegrationGuide.pdf.
TABLE E.5
Summary of ASP.NET SDK Profile-related Interfaces and Classes Description This interface defines the basic information that PayPal needs to know about a user of the PayPal Web Service APIs. Developers must create an instance of IAPIProfile for each account that accesses the APIs. For single-merchant developers, only a single IAPIProfile instance is needed. PayPal provides a default implementation class called DefaultAPIProfile suitable for the needs of most SDK developers. However, you are free to write a custom implementation if you need additional functionality the default class does not offer. This class creates the IAPIProfile object. It contains static methods that handle the instantiation and construction of profile objects. This interface defines the basic information that PayPal needs to know about a user of PayPals Encrypted Website Payments (EWP) service. Developers must create an instance of EWPProfile for each account that generates the encrypted button code; for single-merchant users this will just be a single instance). PayPal provides a basic implementation class called DefaultEWPProfile suitable for the needs of most SDK developers. However, you are free to write a custom implementation if you need functionality the default class does not offer.
Sample Applications
The PayPal SDK includes sample applications in the SDK_root\samples\ASPNET folder. The samples\ASPNET folder is divided into subfolders by products.
TABLE E.6 Samples by Product Products DoCapture
150
February 2007
Developers Guide
Subfolder in SDK_Root\samples\ASPNET
IMPO RTANT: You must protect the API Signature values in your implementation. Consider
storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production.
Developers Guide
February 2007
151
must protect the API Certificate values in your implementation. Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it. The sample code does not store these values securely. The sample code should never be used in production.
sure that you are logged in as an administrator, that IIS running, and that WinHttpCertCfg.exe is in your PATH.
To install the samples in Microsoft IIS: 1. Run SDK_root\samples\ASPNET\InstallSample.bat. 2. To enable logging, change the permissions on the localComputerName\ASPNET folder to Full Control. InstallSample.bat does the following: Creates a virtual directory named PaypalASPNETSample in IIS that points to SDK_root\samples\ASPNET. Loads the sample API certificate SDK_root\samples\Certs\sdk-seller.p12 into the Microsoft Windows system store. Uses the WinHttpCertCfg.exe command to grant unlimited access for account Everyone to that certificate.
152
February 2007
Developers Guide
Developers Guide
February 2007
153
154
February 2007
Developers Guide
F
Country
Country Codes
N O T E : This
Country
Code
BY BE BZ BJ BM BT BO BA BW BV BR IO BN BG BF BI KH CM CA CV KY
BELGIUM BELIZE BENIN BERMUDA BHUTAN BOLIVIA BOSNIA AND HERZEGOVINA BOTSWANA BOUVET ISLAND BRAZIL BRITISH INDIAN OCEAN TERRITORY BRUNEI DARUSSALAM BULGARIA BURKINA FASO BURUNDI CAMBODIA CAMEROON CANADA CAPE VERDE CAYMAN ISLANDS
AFGHANISTAN LAND ISLANDS ALBANIA ALGERIA AMERICAN SAMOA ANDORRA ANGOLA ANGUILLA ANTARCTICA ANTIGUA AND BARBUDA ARGENTINA ARMENIA ARUBA AUSTRALIA AUSTRIA AZERBAIJAN BAHAMAS BAHRAIN BANGLADESH BARBADOS
AF AX AL DZ AS AD AO AI AQ AG AR AM AW AU AT AZ BS BH BD BB
155
Country Codes
Country
Code
Country
Code
CENTRAL AFRICAN REPUBLIC CHAD CHILE CHINA CHRISTMAS ISLAND COCOS (KEELING) ISLANDS COLOMBIA COMOROS CONGO CONGO, THE DEMOCRATIC REPUBLIC OF THE COOK ISLANDS COSTA RICA COTE D'IVOIRE CROATIA CUBA CYPRUS CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA DOMINICAN REPUBLIC ECUADOR EGYPT EL SALVADOR
CF TD CL CN CX CC CO KM CG CD
EQUATORIAL GUINEA ERITREA ESTONIA ETHIOPIA FALKLAND ISLANDS (MALVINAS) FAROE ISLANDS FIJI FINLAND FRANCE FRENCH GUIANA FRENCH POLYNESIA FRENCH SOUTHERN TERRITORIES GABON GAMBIA GEORGIA GERMANY GHANA GIBRALTAR GREECE GREENLAND GRENADA GUADELOUPE GUAM GUATEMALA GUERNSEY
GQ ER EE ET FK FO FJ FI FR GF PF TF GA GM GE DE GH GI GR GL GD GP GU GT GG
CK CR CI HR CU CY CZ DK DJ DM DO EC EG SV
156
Country
Code
Country
Code
GUINEA GUINEA-BISSAU GUYANA HAITI HEARD ISLAND AND MCDONALD ISLANDS HOLY SEE (VATICAN CITY STATE) HONDURAS HONG KONG HUNGARY ICELAND INDIA INDONESIA IRAN, ISLAMIC REPUBLIC OF IRAQ IRELAND ISLE OF MAN ISRAEL ITALY JAMAICA JAPAN JERSEY JORDAN KAZAKHSTAN KENYA KIRIBATI
GN GW GY HT HM VA HN HK HU IS IN ID IR IQ IE IM IL IT JM JP JE JO KZ KE KI
KOREA, REPUBLIC OF KUWAIT KYRGYZSTAN LAO PEOPLE'S DEMOCRATIC REPUBLIC LATVIA LEBANON LESOTHO LIBERIA LIBYAN ARAB JAMAHIRIYA LIECHTENSTEIN LITHUANIA LUXEMBOURG MACAO MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF MADAGASCAR MALAWI MALAYSIA MALDIVES MALI MALTA MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MAYOTTE MEXICO
KR KW KG LA LV LB LS LR LY LI LT LU MO MK
MG MW MY MV ML MT MH MQ MR MU YT MX
Country Codes
Country
Code
Country
Code
MICRONESIA, FEDERATED STATES OF MOLDOVA, REPUBLIC OF MONACO MONGOLIA MONTSERRAT MOROCCO MOZAMBIQUE MYANMAR NAMIBIA NAURU NEPAL NETHERLANDS NETHERLANDS ANTILLES NEW CALEDONIA NEW ZEALAND NICARAGUA NIGER NIGERIA NIUE NORFOLK ISLAND NORTHERN MARIANA ISLANDS NORWAY OMAN PAKISTAN
FM MD MC MN MS MA MZ MM NA NR NP NL AN NC NZ NI NE NG NU NF MP NO OM PK
PALAU PALESTINIAN TERRITORY, OCCUPIED PANAMA PAPUA NEW GUINEA PARAGUAY PERU PHILIPPINES PITCAIRN POLAND PORTUGAL PUERTO RICO QATAR REUNION ROMANIA RUSSIAN FEDERATION RWANDA SAINT HELENA SAINT KITTS AND NEVIS SAINT LUCIA SAINT PIERRE AND MIQUELON SAINT VINCENT AND THE GRENADINES SAMOA SAN MARINO
PW PS PA PG PY PE PH PN PL PT PR QA RE RO RU RW SH KN LC PM VC WS SM
158
Country
Code
Country
Code
SAO TOME AND PRINCIPE SAUDI ARABIA SENEGAL SERBIA AND MONTENEGRO SEYCHELLES SIERRA LEONE SINGAPORE SLOVAKIA SLOVENIA SOLOMON ISLANDS SOMALIA SOUTH AFRICA SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS SPAIN SRI LANKA SUDAN SURINAME SVALBARD AND JAN MAYEN SWAZILAND SWEDEN SWITZERLAND SYRIAN ARAB REPUBLIC TAIWAN, PROVINCE OF CHINA TAJIKISTAN
ST SA SN CS SC SL SG SK SI SB SO ZA GS
TANZANIA, UNITED REPUBLIC OF THAILAND TIMOR-LESTE TOGO TOKELAU TONGA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS AND CAICOS ISLANDS TUVALU UGANDA UKRAINE
TZ TH TL TG TK TO TT TN TR TM TC TV UG UA AE GB US UM UY UZ VU VE VN
ES LK SD SR SJ SZ SE CH SY TW TJ
UNITED ARAB EMIRATES UNITED KINGDOM UNITED STATES UNITED STATES MINOR OUTLYING ISLANDS URUGUAY UZBEKISTAN VANUATU VENEZUELA VIET NAM
Country Codes
Country
Code
VIRGIN ISLANDS, U.S. WALLIS AND FUTUNA WESTERN SAHARA YEMEN ZAMBIA ZIMBABWE
VI WF EH YE ZM ZW
160
Index
A
ACCT 19, 45, 73 ACK 16, 17, 85 Add/Remove Programs 149 Address Verification System 19 ADDRESSOWNER 77 ADDRESSSTATUS 60, 78 ADDROVERRIDE 56 AMT 40 DoAuthorization request 70 DoAuthorization response 70 DoCapture 67 DoCapture response 68 DoDirectPayment 45 DoExpressCheckoutPayment 61 DoExpressCheckoutPayment response 65 DoReauthorization 71 GetTransactionDetails response 79 refunding 40 RefundTransaction 72 TransactionSearch 74 API Certificate 16 API Credentials 14 API Password 143, 151 API Signature 16 api.sandbox.paypal.com 16 api-3t.paypal.com 16 api-3t.sandbox.paypal.com 16 APIProfile interface 142 AUCTIONITEMNUMBER 74 AUD 43 Australian Dollar 43 AUTHORIZATIONID 37, 67, 68 DoReauthorization request 71 DoReauthorization response 72 DoVoid 71 DoVoid response 71 AuthorizationID 64 AVS 19
B
BUILD 16, 17, 85 BUSINESS 60 BUTTONSOURCE 47, 62 BUYERID 82
C
CAD 43 Canadian Dollar 43 Canceled-Reversal 69, 80 Capturing A Partial Amount of an Authorization 38 Capturing the Full Amount of an Authorization 37 Card Verification Value. See CVV2. certificate sample 144, 152 CertificateAPIProfile class 142 CHF 43 chm documentation 149 CITY 45 CLASSPATH 140 CLOSINGDATE 82 ColdFusion 137 Completed 69, 80 COMPLETETYPE 37, 38, 67 CORRELATIONID 16, 17, 85 COUNTRYCODE 46, 59 CREDITCARDTYPE 19, 45 currency codes 43 CURRENCYCODE 46, 54, 62, 65, 67, 70, 71, 83 CUSTOM 47, 55, 60, 61, 81 CVV2 19, 48 Czech Koruna 43 CZK 43
D
Danish Krone 43 DefaultAPIProfile class 150 Denied 69, 80 Denied (transaction status) 75
February 2007
161
Index
DESC 47, 55, 61 digital certificate sample 144, 152 Direct Payment 143 Direct Payment API 151 DKK 43 DoAuthorization 37 DoCapture 20, 37, 143, 150 documentation 146 DoDirectPayment 19 DoReauthorization 37 DoVoid 37, 143, 151
HDRBACKCOLOR 57 HDRBORDERCOLOR 57 HDRIMG 57 HKD 44 Hong Kong Dollar 44 HUF 44 Hungarian Forint 44
I
IAPIProfile interface 150 IIS 152 Including a Note with the Refund 40 InstallSample.bat 152 INVNUM 47, 55, 60, 61, 67, 73, 81 IPADDRESS 19, 44 ITEMAMT 21, 34, 62
E
EFFECTIVEDATE 82 EMAIL 48, 55, 59, 77 TransactionSearch 73 EMAILSUBJECT 83 ENDDATE 73 EUR 43 Euro 43 EWP profile defined 142, 149 EWPProfile interface 142, 150 EXCHANGERATE 65, 69, 79 EXPDATE 19, 45 Expired 69, 80 Express Checkout 143, 151
J
Japanese Yen 44 Java Development Kit 1.4 139 Javadoc documentation for PayPal SDK 141 JPY 44 JSP 143
K
Koruna 43 Krona 44 Krone 43
F
FEEAMT 65, 68, 79 FEEREFUNDAMT 72 FIRSTNAME 19, 45, 59, 74, 77 Forint 44
L
L 63 L_AMTn 21, 33, 48, 63, 76, 81, 83 L_DESCn 81 L_EMAILn 75, 83 L_FEEAMTn 76 L_NAMEn 21, 33, 47, 62, 76 L_NETAMTn 76 L_NOTEn 83 L_NUMBERn 21, 33, 47, 63, 81 L_OPTIONSn 82 L_QTY 63 L_QTYn 21, 33, 47, 63, 81 L_RECEIVERIDn 83
G
GBP 43 Get Transaction Details 151 GetTransactionDetails 42, 143 GROSSREFUNDAMT 72
H
HANDLINGAMT 21, 34, 46, 62
162
February 2007
Index
L_STATUSn 76 L_TAXAMTn 21, 33, 48, 63 L_TIMESTAMPn 75 L_TIMEZONEn 75 L_TRANSACTIONIDn 76 L_TYPEn 75 L_UNIQUEIDn 83 LASTNAME 19, 45, 59, 74, 77 LOCALECODE 56 log4j.properties 141 log4net 147 logging levels 147
O
ORDERTIME 65, 68, 79
P
PAGESTYLE 56 PARENTTRANSACTIONID 68, 78 PASSWORD 82 PAYERBUSINESS 77 PAYERID 59, 61, 77 PAYERSTATUS 59, 77 PAYFLOWCOLOR 57 PAYMENTACTION 19, 44, 55, 61 PaymentAction 64 must be Authorization if CreditCardType is Switch or Solo 45 PAYMENTSTATUS 66, 69, 80 PAYMENTTYPE 65, 68, 79 paypal tag in Web.Config 147 PayPal-supported currencies 43 Pending 69, 80 Pending (transaction status) 75 PENDINGREASON 66, 80 PendingReason 69, 80 PERIOD 82 PHONENUM 48, 58, 60 PLN 44 Polish Zloty 44 Pound Sterling 43 Processed 69, 80 Processing (transaction status) 75 ProfileFactory class 143, 150 Profiles class 143 PWD 14
M
MassPay 151 MAXAMT 54 METHOD 14 DoAuthorization 69 DoCapture 67 DoDirectPayment 44 DoExpressCheckoutPayment 61 DoReauthorization 71 DoVoid 70 GetExpressCheckoutDetails 58 GetTransactionDetails 76 MassPay 83 RefundTransaction 72 TransactionSearch 73 Microsoft .NET 1.1 145 MIDDLENAME 59, 74, 77 MULTIITEM 82
N
NETREFUNDAMT 72 New Zealand Dollar 44 NOK 44 Norwegian Krone 44 NOSHIPPING 56 NotComplete 38 NOTE DoCapture 67 DoVoid request 71 GetTransactionDetails response 81 RefundTransaction 72 NOTIFYURL 46, 47, 62
R
REASONCODE 66, 81 ReasonCode 69, 80 REATTEMPT 82 RECEIPTID 68, 73, 78 RECEIVER 73 RECEIVERBUSINESS 77
February 2007
163
Index
RECEIVEREMAIL 77 RECEIVERID 77 RECEIVERTYPE 83 RECURRENCES 82 RECURRING 82 Refunded 69, 80 Refunding A Partial Amount 40 Refunding The Full Amount of a Transaction 40 RefundTransaction 40, 143, 151 REFUNDTRANSACTIONID 72 REFUNDTYPE 40, 72 REQCONFIRMSHIPPING 55 RETRYTIME 82 Reversed 69, 80 Reversed (transaction status) 75
src 147 STARTDATE 41, 73 STATE 45 STATUS 75 STREET 45 STREET2 48 SUBJECT 14 SUBSCRIPTIONAMT 82 SUBSCRIPTIONDATE 82 SUBSCRIPTIONID 82 Success (transaction status) 75 successResponseFields, defined 16 SUFFIX 59, 74, 77 Swedish Krona 44 Swiss Franc 43 system store 152
S
SALESTAX 81 SALUTATION 59, 74, 77 Sample API Certificate 144, 152 sample API credentials 143, 144, 151, 152 Sample API Signature 143, 151 sample application 150 SampleApp 143 Sandbox 16 sdk-seller.p12 144, 147, 152 sdk-seller_api1.sdk.com 143, 144, 151, 152 sdk-three_api1.sdk.com 143, 151 SEK 44 Service Pack 1 for Microsoft .NET Framework 1.1 146 SETTLEAMT 65, 68, 79 SGD 44 SHIPPINGAMT 21, 34, 46, 62 SHIPTOCITY 20, 49, 57, 60, 63, 78 SHIPTOCOUNTRY 20 SHIPTOCOUNTRYCODE 49, 57, 60, 64, 77 SHIPTONAME 20, 49, 57, 60, 63, 78 SHIPTOPHONENUM 20, 49, 64, 78 SHIPTOSTATE 49, 57, 60, 64, 78 SHIPTOSTREET 20, 49, 57, 60, 63, 78 SHIPTOSTREET2 20, 49, 58, 60, 64, 78 SHIPTOZIP 20, 49, 57, 60, 64, 78 SIGNATURE 14 SignatureAPIProfile class 142 Singapore Dollar 44 source files 147
T
TAXAMT 21, 34, 47, 62, 65, 68, 79 TOKEN 64 DoExpressCheckoutPayment 61 GetExpressCheckoutDetails 59 GetExpressCheckoutDetails response 59 SetExpressCheckout 56 SetExpressCheckout response 58 Token 24, 58 token 24, 58 TRANSACTIONCLASS 74 TRANSACTIONENTITY 70 TRANSACTIONID 37 DoAuthorization 70 DoAuthorization response 70 DoCapture response 68 DoExpressCheckoutPayment response 64 GetTransactionDetails 76 GetTransactionDetails response 78 RefundTransaction 72 TransactionSearch 73 TransactionSearch 41, 143, 151 TRANSACTIONSTATUS 75 TRANSACTIONTYPE 64, 68, 79 TransactionType 66, 81
U
U.S. Dollar 44
164
February 2007
Index
UrlDecode 17 urldecode() 17 URLDecoder 17 URLDecodeurlEncodedString 17 URLEncode 15 UrlEncode 15 urlencode() 15 URL-encoded string 13 URLEncodedFormatstring 15 URLEncoder.encode 15 URL-encoding 15, 16, 43 methods 15 USD 44 USER 14 USERNAME 82 UTC/GMT 75
V
VERSION 16, 17, 85 VERSION=2.3 13, 14 Voided 69, 80
W
Web.config 147, 148 paypal tag 147 Website Payments Standard Integration Guide 142, 150 WinHttpCertCfg.exe 152 WinHttpPCertCfg.exe 152
Y
Yen 44
Z
ZIP 46 Zloty 44
February 2007
165