Last Updated: July 2006

For Professional Use Only
Currently only available in English.
A usage Professional Uniquement
Disponible en Anglais uniquement pour l'instant.
Website Payments
Pro Integration Guide
© 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.
PayPal Website Payments Pro
Integration Guide
July 2006 3
1
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Complementary Technical Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 1 Website Payments Pro Overview . . . . . . . . . . . . . . 17
How Website Payments Pro Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Direct Payment API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Express Checkout Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Website Payments Pro Business Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Funding Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Technical Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
The PayPal SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Get Started Quickly: Integration Center . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Chapter 2 How Express Checkout Works . . . . . . . . . . . . . . . 23
Express Checkout Integration Points: Technical View. . . . . . . . . . . . . . . . . . . . 25
Relationship to Authorization & Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Step 1a: Customer Selects PayPal on Your Website . . . . . . . . . . . . . . . . . . . . 28
Step 1b: Integration Point 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Usage Notes About SetExpressCheckout Elements . . . . . . . . . . . . . . . . . . 29
Step 2a: Customer Approves Use of PayPal . . . . . . . . . . . . . . . . . . . . . . . . 34
Step 2b: Customer Returns to Your Website. . . . . . . . . . . . . . . . . . . . . . . . . 36
Step 2c: Integration Point 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
ReturnURL, CancelURL, and the Express Checkout Token . . . . . . . . . . . . . . 37
Usage Notes About GetExpressCheckoutDetails Elements. . . . . . . . . . . . . . . 37
Step 3a: Customer Completes Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Step 3b: Integration Point 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Usage Notes About DoExpressCheckoutPaymentRequest Elements . . . . . . . . . 41
Step 4: Customer Notified Order Is Complete . . . . . . . . . . . . . . . . . . . . . . . . 44
Contents
4 July 2006
Chapter 3 How Direct Payment API Works . . . . . . . . . . . . . . . 45
Technical Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Relationship to Authorization & Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Chapter 4 How Authorization & Capture Works . . . . . . . . . . . . 49
Fundamental Authorization Process With the APIs . . . . . . . . . . . . . . . . . . . . . 50
Order Authorizations Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Optimal Buyer Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Capturing Funds on Basic Authorizations . . . . . . . . . . . . . . . . . . . . . . . . 56
Buyer Approval for Basic Authorizations. . . . . . . . . . . . . . . . . . . . . . . . . 57
Voiding Basic Authorizations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Chapter 5 Design Choices for Best Buying Experience . . . . . . . . 59
Implementation Point A: Express Checkout Shortcut . . . . . . . . . . . . . . . . . . . . 60
Button Placement Business Rules for Express Checkout Shortcut . . . . . . . . . . . 60
Implementation Point B: Express Checkout Mark . . . . . . . . . . . . . . . . . . . . . . 62
Button Placement Business Rules for Express Checkout Mark . . . . . . . . . . . . . 64
Treatment When PayPal Is Selected . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Sending Shipping Address Information to PayPal . . . . . . . . . . . . . . . . . . . . 65
Best Buying Experience in Shortcut Implementation . . . . . . . . . . . . . . . . . . . . 67
Move Important Fields to End of Checkout . . . . . . . . . . . . . . . . . . . . . . . 67
Use the Information Returned by PayPal . . . . . . . . . . . . . . . . . . . . . . . . 67
Best Buying Experience in Shortcut or Mark Implementations . . . . . . . . . . . . . . . 70
Allow the Customer to Confirm Before Calling DoExpressCheckoutPayment. . . . . . 70
Edit Shipping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Reapproving PayPal at Integration Point 3 . . . . . . . . . . . . . . . . . . . . . . . 72
Chapter 6 Express Checkout API . . . . . . . . . . . . . . . . . . . . 75
PayPal-supported Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
SetExpressCheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Diagram of Set ExpressCheckout Types . . . . . . . . . . . . . . . . . . . . . . . . 76
SetExpressCheckoutRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
SetExpressCheckoutResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
GetExpressCheckoutDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Diagram of GetExpressCheckoutDetails Types . . . . . . . . . . . . . . . . . . . . . 83
GetExpressCheckoutDetailsRequest . . . . . . . . . . . . . . . . . . . . . . . . . . 84
GetExpressCheckoutDetailsResponse . . . . . . . . . . . . . . . . . . . . . . . . . 84
July 2006 5
Contents
DoExpressCheckoutPayment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Diagram of DoExpressCheckoutPayment Types . . . . . . . . . . . . . . . . . . . . 87
DoExpressCheckoutPaymentRequest. . . . . . . . . . . . . . . . . . . . . . . . . . 89
DoExpressCheckoutPaymentResponse. . . . . . . . . . . . . . . . . . . . . . . . . 93
Chapter 7 Direct Payment API . . . . . . . . . . . . . . . . . . . . . 97
Diagram of DoDirectPayment Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
DoDirectPaymentRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
DoDirectPaymentResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Chapter 8 Authorization & Capture API . . . . . . . . . . . . . . . 111
Funds Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
DoCapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
Diagram of DoCapture Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
DoCaptureRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
DoCaptureResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
DoAuthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Diagram of DoAuthorization Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
DoAuthorizationRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
DoAuthorizationResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
DoVoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Diagram of DoVoid Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
DoVoidRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
DoVoidResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
DoReauthorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Diagram of DoReauthorization Types . . . . . . . . . . . . . . . . . . . . . . . . . .121
DoReauthorizationRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
DoReauthorizationResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Appendix A Express Checkout API Error Codes, Short Message, and Long
Messages123
Express Checkout API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Appendix B Direct Payment API Error Codes, Short Message, and Long
Messages139
Contents
6 July 2006
Direct Payment API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Appendix C Authorization & Capture API Error Codes, Short Message, and
Long Messages149
Appendix D Country Codes . . . . . . . . . . . . . . . . . . . . . . 155
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
July 2006 7
1
List of Tables
Table P.1 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Table P.2 PayPal Technical Documentation . . . . . . . . . . . . . . . . . . . . . 14
Table 2.1 Steps in Integrating Express Checkout . . . . . . . . . . . . . . . . . . . 24
Table 2.2 Express Checkout Program Flow-of-Control and Integration Points . . . . 27
Table 2.3 SetExpressCheckoutRequest Usage Notes . . . . . . . . . . . . . . . . 30
Table 2.4 SetExpressCheckoutResponse Usage Notes . . . . . . . . . . . . . . . 32
Table 2.5 GetExpressCheckoutDetailsResponse Usage Notes . . . . . . . . . . . 37
Table 2.6 Shipping, Billing and Order Total Usage . . . . . . . . . . . . . . . . . . 40
Table 2.7 DoExpressCheckoutPaymentRequest Usage Notes . . . . . . . . . . . 42
Table 3.1 Steps in Checkout with Direct Payment API . . . . . . . . . . . . . . . . 45
Table 4.1 PayPal Products Supporting Authorization & Capture . . . . . . . . . . . 51
Table 4.2 Simple Order Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Table 4.3 Complex Order Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Table 4.4 Concurrent Authorizations Scenario . . . . . . . . . . . . . . . . . . . . 53
Table 4.5 Total Capture Hits Relative Tolerance with Open Authroziations Scenario 54
Table 4.6 Void Authorizations Scenario . . . . . . . . . . . . . . . . . . . . . . . 55
Table 4.7 Partial Capture Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Table 4.8 Complete Capture Scenario . . . . . . . . . . . . . . . . . . . . . . . . 56
Table 5.1 SetExpressCheckoutRequest Usage Notes: Shipping Address . . . . . . 66
Table 5.2 SetExpressCheckoutRequest Usage Notes for “Edit Shipping” . . . . . . 72
Table 6.1 PayPal-supported Currencies and Currency Codes . . . . . . . . . . . . 75
Table 6.2 SetExpressCheckoutRequest Fields . . . . . . . . . . . . . . . . . . . . 77
Table 6.3 Address (Shipping Address): AddressType Elements . . . . . . . . . . . 81
Table 6.4 SetExpressCheckoutResponse Fields . . . . . . . . . . . . . . . . . . . 82
Table 6.5 GetExpressCheckoutDetailsRequest Fields . . . . . . . . . . . . . . . . 84
Table 6.6 GetExpressCheckoutDetailsResponse Fields . . . . . . . . . . . . . . . 84
Table 6.7 Response: PayerInfoType Elements . . . . . . . . . . . . . . . . . . . . 85
Table 6.8 Response: PayerName Elements . . . . . . . . . . . . . . . . . . . . . 86
Table 6.9 Response: AddressType Fields . . . . . . . . . . . . . . . . . . . . . . 86
Table 6.10 DoExpressCheckoutPaymentRequest Fields . . . . . . . . . . . . . . . 89
Table 6.11 Request: PaymentDetailsType Fields . . . . . . . . . . . . . . . . . . . 90
Table 6.12 Request: ShipToAddress: AddressType Fields . . . . . . . . . . . . . . 92
List of Tables
8 July 2006
Table 6.13 Request: PaymentDetailsItemType Fields . . . . . . . . . . . . . . . . . 93
Table 6.14 DoExpressCheckoutPaymentResponse Fields . . . . . . . . . . . . . . 94
Table 6.15 Response: PaymentInfoType Elements . . . . . . . . . . . . . . . . . . 94
Table 7.1 DoDirectPaymentRequest Fields . . . . . . . . . . . . . . . . . . . . . 98
Table 7.2 CreditCardDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . 99
Table 7.3 Request: PaymentDetailsType Fields . . . . . . . . . . . . . . . . . . .100
Table 7.4 Request: ShipToAddress: AddressType Fields . . . . . . . . . . . . . .102
Table 7.5 StateOrProvince: Abbreviations for Canada and U.S. . . . . . . . . . . .103
Table 7.6 Request: PaymentDetailsItemType Fields . . . . . . . . . . . . . . . . .106
Table 7.7 CardOwner: PayerInfoType Fields . . . . . . . . . . . . . . . . . . . . .106
Table 7.8 CardOwner: AddressType Fields . . . . . . . . . . . . . . . . . . . . . .107
Table 7.9 DoDirectPaymentResponse Fields . . . . . . . . . . . . . . . . . . . . .108
Table 7.10 AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Table 7.11 CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . .109
Table 8.1 Authorization & Capture API Names, Purposes, and Types of Authorization .
111
Table 8.2 DoCaptureRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . 113
Table 8.3 DoCaptureResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . 114
Table 8.4 Response: PaymentInfoType Elements . . . . . . . . . . . . . . . . . . 114
Table 8.5 DoAuthorizationRequest Fields . . . . . . . . . . . . . . . . . . . . . . 118
Table 8.6 DoAuthorizationResponse Fields . . . . . . . . . . . . . . . . . . . . . 118
Table 8.7 DoVoidRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Table 8.8 DoVoidResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . .120
Table 8.9 DoReauthorizationRequest Fields . . . . . . . . . . . . . . . . . . . . .122
Table 8.10 DoReauthorizationResponse Fields . . . . . . . . . . . . . . . . . . . .122
Table A.1 SetExpressCheckout API Errors . . . . . . . . . . . . . . . . . . . . . .123
Table A.2 GetExpressCheckoutDetails API Errors . . . . . . . . . . . . . . . . . .128
Table A.3 DoExpressCheckoutPayment API Errors . . . . . . . . . . . . . . . . .130
Table B.1 Direct Payment API Errors . . . . . . . . . . . . . . . . . . . . . . . . .139
Table C.1 Authorization & Capture API Error Messages . . . . . . . . . . . . . . .149
Website Payments Pro Integration Guide July 2006 9
1
List of Figures
Figure 1.1 High-Level View of Website Payments Pro . . . . . . . . . . 17
Figure 2.1 Generalized Customer Checkout . . . . . . . . . . . . . . . 23
Figure 2.2 Express Checkout Integration Points: Technical View . . . . . 26
Figure 2.3 PayPal Express Checkout Button Before Shipping Address
Information 28
Figure 2.4 Express Checkout Integration Point 1 . . . . . . . . . . . . 29
Figure 2.5 PayPal Login Page . . . . . . . . . . . . . . . . . . . . . 34
Figure 2.6 PayPal Review Page . . . . . . . . . . . . . . . . . . . . . 35
Figure 2.7 Express Checkout Integration Point 2 . . . . . . . . . . . . 36
Figure 2.8 Example of Order Review Page . . . . . . . . . . . . . . . 39
Figure 2.9 Express Checkout Integration Point 3 . . . . . . . . . . . . 41
Figure 2.10 Example of Order Complete Page . . . . . . . . . . . . . . 44
Figure 3.1 Generalized Customer Checkout with Direct Payment API . . . 45
Figure 3.2 PayPal Direct Payment Integration Point: Technical View . . . 46
Figure 4.1 Fundamental Authorization & Capture Process with APIs . . . 50
Figure 5.1 Implementation Points A and B . . . . . . . . . . . . . . . 59
Figure 5.2 Example of Button Placement for Express Checkout Shortcut . 60
Figure 5.3 Placement of Express Checkout Mark Implementation . . . . . 62
Figure 5.4 Example of Button Placement for Express Checkout Mark . . . 63
Figure 5.5 Payment Methods in Horizontal Design . . . . . . . . . . . . 64
Figure 5.6 Payment Methods as Drop-Down SELECT List . . . . . . . . . 64
Figure 5.7 Example of Billing Information Page with PayPal Selected . . . 65
Figure 5.8 Example of Optimal Order Review Page after Return from PayPal 67
Figure 5.9 Example of Optimal Shipping Method Page . . . . . . . . . . 68
Figure 5.10 Example of Optimal Billing Page . . . . . . . . . . . . . . . 69
Figure 5.11 Example of Edit Shipping Button Treatment . . . . . . . . . 71
Figure 5.12 Example Message for Reapproving PayPal . . . . . . . . . . 73
Figure 6.1 SetExpressCheckout Types . . . . . . . . . . . . . . . . . 76
Figure 6.2 GetExpressCheckout Types . . . . . . . . . . . . . . . . . 83
Figure 6.3 DoExpressCheckoutPayment Types . . . . . . . . . . . . . 88
Figure 7.1 DoDirectPayment Types . . . . . . . . . . . . . . . . . . . 97
Figure 8.1 DoCapture Types . . . . . . . . . . . . . . . . . . . . . . 112
List of Figures
10 July 2006 Website Payments Pro Integration Guide
Figure 8.2 DoAuthorization Types . . . . . . . . . . . . . . . . . . . 117
Figure 8.3 DoVoid Types . . . . . . . . . . . . . . . . . . . . . . . . 119
Figure 8.4 DoReauthorization Types . . . . . . . . . . . . . . . . . . 121
Website Payments Pro Integration Guide July 2006 11
Preface
This Document
This release of the Website Payments Pro Integration Guide, a document that describes PayPal
Direct Payment and PayPal Express Checkout as payment solutions for customer checkout on
your website, supercedes the previous release issued in May, 2006.
Intended Audience
This document is written for merchants who use either PayPal Direct Payment or PayPal
Express Checkout and the programmers who implement these products on a merchant’s
website.
Background Information about the PayPal Web Services API
Consult the PayPal Web Services API Reference for information about the following:
z Architecture of the PayPal Web Services API, such as security and authentication basics
z The location of PayPal’s Web Services Definition Language (WSDL) and X-Schema
Definition files
z The structure of SOAP requests and responses
z Other APIs, such as GetTransactionDetails and TransactionSearch
Organization of This Document
Chapter 1, “Website Payments Pro Overview,” describes what Website Payments Pro is, who
can use it, what developers need to know to make it work, and why it is the perfect checkout
solution for your website.
Chapter 2, “How Express Checkout Works,” is a detailed, step-by-step explanation of how
Express Checkout works and how it can be integrated into your checkout process.
Chapter 3, “How Direct Payment API Works,” presents a more in-depth technical overview of
how the Direct Payment API works.
Chapter 4, “How Authorization & Capture Works,” details how Authorization & Capture
works.
Chapter 5, “Design Choices for Best Buying Experience,” details guidelines for placing
PayPal logo graphics on your website, variations on those guidelines, and special
considerations in integrating Express Checkout in some cases of the customer experience,
such as handling shipping addresses and reapproving the use of PayPal.
Chapter 6, “Express Checkout API” details the required and optional elements of all SOAP
requests and responses for PayPal Express Checkout.
Chapter 7, “Direct Payment API” details the required and optional elements of all SOAP
requests and responses for PayPal Direct Payment.
Preface
12 July 2006 Website Payments Pro Integration Guide
Chapter 8, “Authorization & Capture API” details the required and optional elements of all
SOAP requests and responses for Authorization & Capture.
Notational Conventions
This document uses typefaces to identify the characteristics of text. These typefaces and the
characteristics they imply are described below:
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:
Typeface How Used
serif italics 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.
San-serif
oblique
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.
Text attribute How Used
xxxxxx Hypertext link to a page in the current document or to another document in the set.
xxxxxx Hypertext link to a URL or that initiates a web action, such as sending mail.
Website Payments Pro Integration Guide July 2006 13
Preface
Complementary Technical Documentation
Documentation Problems
If you discover any errors in or have any problems with this documentation, please e-mail 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 (located at the foot of every page),
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 Website Payments Pro Integration Guide.
Complementary Technical Documentation
All PayPal technical documentation is listed here. The description of each guide indicates its
subject matter and documentation necessary for effective use of the guide.
TABLE P.1 Revision History
Date Description
July 2006 Direct Payment API now supports the Switch and Solo credit cards and can be
used with any PayPal-supported currency.
May 2006 Miscellaneous updates
March 2006 Miscellaneous corrections
January 2006 Additional API error messages for Express Checkout: 10445, 10446.
December 2005 Removed erroneous description that stated that the SetExpressCheckoutRequest
field cpp-header-image must be URL-encoded.
Preface
Complementary Technical Documentation
14 July 2006 Website Payments Pro Integration Guide
TABLE P.2 PayPal Technical Documentation
Guide Title Description Prerequisites
Website Payments
Standard
Integration Guide
Details basic PayPal payment process for shopping cart and single-item
purchase. Account Profile settings for variations on basic payment process.
Customization of PayPal's payment pages. HTML FORM variables for control
of payment process.
https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_Integratio
nGuide.pdf
None
Express Checkout
Integration Guide
Details use of Express Checkout API. PayPal placement on merchants' websites
and related business rules.
https://www.paypal.com/en_US/pdf/PP_ExpressCheckout_IntegrationGuide.p
df
Website Payments
Standard
Integration Guide
Website Payments
Pro Integration
Guide
Details use of Express Checkout and Direct Payment APIs. PayPal placement
on merchants' websites and related business logic.
https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsPro_IntegrationGui
de.pdf
Website Payments
Standard
Integration Guide
Authorization &
Capture Integration
Guide
Details use of PayPal website and API for authorization and capture; relates
Authorization & Capture to Express Checkout and Direct Payment.
https://www.paypal.com/en_US/pdf/PP_AuthCapture_IntegrationGuide.pdf
z Website
Payments
Standard
Integration
Guide
z Website
Payments Pro
Integration
Guide
z API Reference
Order Management
Integration Guide
Details Instant Payment Notification (IPN) and Payment Data Transfer (PDT)
for automated receipt of payment information after payment completion.
Details IPN HTML FORM variables and their meanings. Also includes
information about Downloadable History Logs.
https://www.paypal.com/en_US/pdf/PP_OrderManagement_IntegrationGuide.
pdf
Website Payments
Standard
Integration Guide
Website Payments Pro Integration Guide July 2006 15
Preface
Complementary Technical Documentation
Java SDK Guide
.NET SDK Guide
Classic ASP Guide
PHP SDK Guide
Details the use of the PayPal Software Development Kits for Java, Microsoft
.NET, Microsoft Classic ASP, and PHP to simplify use of the PayPal Web
Services API.
https://www.paypal.com/en_US/pdf/PP_SDK_Java_Guide.pdf
https://www.paypal.com/en_US/pdf/PP_SDK_NET_Guide.pdf
https://www.paypal.com/en_US/pdf/PP_SDK_ClassicASP_Guide.pdf
https://www.paypal.com/en_US/pdf/PP_SDK_PHP_Guide.pdf
z Website
Payments
Standard
Integration
Guide
z Website
Payments Pro
Integration
Guide
z Authorization &
Capture
Integration
Guide
z Sandbox User
Guide
z API Reference
Sandbox User
Guide
Describes the PayPal Sandbox testing environment for testing website
payments and Web Services APIs. Details how to get PayPal API digital
certificates.
https://www.paypal.com/en_US/pdf/PP_Sandbox_UserGuide.pdf
All other PayPal
guides for an
understanding of
how products work
Web Services API
Reference
Field-by-field description of all PayPal Web Services APIs, their SOAP
structures, and error messages. Location of PayPal WSDL and XSD files.
https://www.paypal.com/en_US/pdf/PP_APIReference.pdf
None
Subscriptions and
Recurring
Payments Guide
Describes HTML FORM variables for using PayPal for subscriptions to goods
and services.
https://www.paypal.com/en_US/pdf/subscriptions.pdf
Website Payments
Standard
Integration Guide
Virtual Terminal
User Guide
Details how to use the virtual terminal to accept credit card payments.
https://www.paypal.com/en_US/pdf/VT_user_guide.pdf
None
TABLE P.2 PayPal Technical Documentation
Guide Title Description Prerequisites
Preface
Complementary Technical Documentation
16 July 2006 Website Payments Pro Integration Guide
Website Payments Pro Integration Guide July 2006 17
1
Website Payments Pro Overview
With Website Payments Pro, you get the payment processing capabilities of a merchant
account and gateway – plus much more. It is an all-in-one payment solution that includes
PayPal Direct Payment API and PayPal Express Checkout.
z Direct Payment API enables you to accept credit card payments directly on your website.
PayPal remains invisible, so you control the customer experience.
NOTE: The only currency supported by Direct Payment at this time is US dollars (USD).
z PayPal Express Checkout allows PayPal account holders to check out fast with saved
information, and enables you to gain incremental sales from PayPal’s growing base of
users.
NOTE: Express Checkout works with any of the PayPal-supported currencies.
How Website Payments Pro Works
Figure 1.1, “High-Level View of Website Payments Pro,” is an example of a standard
checkout process. Website Payments Pro has the flexibility to work with your unique
checkout process, whether it is one page or has multiple steps.
FIGURE 1.1 High-Level View of Website Payments Pro
After selecting products to purchase, your customer chooses whether they want to pay using
PayPal or pay with credit cards directly on your website.
Website Payments Pro Overview
Direct Payment API Overview
18 July 2006 Website Payments Pro Integration Guide
If your customer pays using credit cards on your website, PayPal processes them in the
background.
If your customer chooses to use PayPal, he is transferred to PayPal to login and select a
shipping address and payment method, and is returned to your website to complete his
purchase.
Once the buyer completes their order, you receive your payment in seconds.
Direct Payment API Overview
The Direct Payment API offers you direct credit card payment processing capability through
PayPal. For credit card transactions, customers can stay on your website as PayPal processes
the payment in the background.
For each payment, Direct Payment API takes the billing address, transaction amount, credit
card information, and item information as inputs. Within seconds, the API returns a
confirmation that the transaction has been processed. Additionally, Direct Payment API lets
you flag potentially fraudulent transactions, and provides you with industry-standard AVS and
CVV2 responses for each transaction.
By integrating Direct Payment API with Express Checkout as part of the Website Payments
Pro solution, you can accept all major payment types, including PayPal, while working with a
single provider that processes and manages all of your online payments for you.
IMPORTANT: Direct Payment API is not a standalone product. You are required to use
Direct Payment API and Express Checkout together as part of the Website
Payments Pro solution. See “Website Payments Pro Business Rules” on
page 19.
The Direct Payment API is not covered by the PayPal Seller Protection Policy (SPP).
Express Checkout Overview
The more convenient it is for your customers to buy from you, the more they'll buy. Express
Checkout allows customers the option to pay quickly through PayPal – and gives your
business more benefits:
z Give buyers more convenience, and get more sales. Since your customers simply log in
to use information they've already entered with PayPal, they save time by completing
transactions in fewer steps. This helps increase loyalty and sales.
z Complete sales on your website, and get more upsell opportunities. Buyers finish their
orders on your website. This gives you more advertising opportunities.
z Help customers feel safer, so they buy more. Buyers prefer to pay with PayPal because
their customer information is kept safe. When they’re confident about the security of their
information, they purchase more.
Website Payments Pro Integration Guide July 2006 19
Website Payments Pro Overview
Website Payments Pro Business Rules
How It Works
After selecting products to purchase, your customers click Checkout with PayPal on your
website.
They’re transferred to PayPal, where they select their payment method, as well as the correct
shipping and billing address, then are returned to your website to complete their purchase.
PayPal automatically gives you the shipping address, email address, and other customer
information to fulfill the order.
With Express Checkout, your buyers finish their orders on your website, not PayPal's, so you
can:
z Get real time notification of successful payments.
z Automate your internal business processes.
z Ensure buyers make it to your final confirmation page.
z Be notified that the buyer's address is confirmed, and ensure you’re eligible for coverage
under PayPal’s Seller Protection Policy.
Website Payments Pro Business Rules
Website Payments Pro must be integrated on your website in the following ways. You must:
1. Present the PayPal Express Checkout button and associated messaging before requesting
shipping address, billing address, and financial information. PayPal account holders should
not be required enter any of this information on your website, because the information is
available from their PayPal accounts. See “Button Placement Business Rules for Express
Checkout Shortcut” on page 60.
2. Display PayPal as an option along side other payment methods, wherever other payment
methods are offered. See “Button Placement Business Rules for Express Checkout Mark”
on page 64.
3. Present the PayPal mark graphic wherever other payment marks are displayed.
NOTE: You can find this logo graphic in the PayPal logo center at the following location:
https://www.paypal.com/logocenter
Compatibility
Website Payments Pro works with many other PayPal products, such as Instant Payment
Notification, Settlement System, Downloadable History Log, Authorization & Capture, and
more.
Website Payments Pro Overview
Funding Sources
20 July 2006 Website Payments Pro Integration Guide
Funding Sources
With Express Checkout, you can accept all major credit and debit cards, bank transfers, and
PayPal balance payments.
With PayPal Direct Payment API, you can accept all major credit and debit cards, including
Visa, Master Card, American Express, and Discover.
Technical Requirements
Integrating Express Checkout API and Direct Payment API requires the knowledge of the
following:
The PayPal SDK
The PayPal SDK for Java, Microsoft .NET, and PHP is a set of tools and programs that eases
application development. Integrated access to the PayPal Web Services APIs is one of the
main features of the PayPal SDK. The PayPal SDK uses the underlying platform’s SOAP
toolkit to communicate with the PayPal API endpoint. Stub classes representing the requests,
the responses, and their data can set request parameters and read response values.
For information about the PayPal SDK, see https://www.paypal.com/sdk.
SOAP-based
XML
SOAP API calls exchange information between PayPal and
the merchant site.
For information about PayPal’s SOAP APIs see, the PayPal
Web Services API Reference. In addition, see information
about the PayPal SDK, below.
SSL
Certificates
The latest encryption technology ensures that data is
communicated safely and securely.
The PayPal
Sandbox
The Sandbox is a simulation of PayPal’s live environment.
PayPal strongly recommends that you test your integration
of Express Checkout with the Sandbox to verify its
completeness.
For information about the Sandbox, see the PayPal
Sandbox User Guide.
Website Payments Pro Integration Guide July 2006 21
Website Payments Pro Overview
Get Started Quickly: Integration Center
Get Started Quickly: Integration Center
PayPal’s Integration Center at https://www.paypal.com/integration has step-by-step details for
getting started with the PayPal Software Development Kits (SDKs), Website Payments Pro,
Express Checkout, Website Payments Standard, Authorization & Capture, Instant Payment
Notification, and more.
Visit the Integration Center at:
https://www.paypal.com/integration
Website Payments Pro Overview
Get Started Quickly: Integration Center
22 July 2006 Website Payments Pro Integration Guide
Website Payments Pro Integration Guide July 2006 23
2
How Express Checkout Works
PayPal Express Checkout is a combination of the checkout process on your website, PayPal
login and review pages on https://www.paypal.com, and PayPal Web Services API SOAP
requests/responses.
To explain how Express Checkout works, this chapter presents a generalized checkout process
and details how Express Checkout can be implemented with it. This generalized checkout
process, which might differ from your own, is shown in Figure 2.1, “Generalized Customer
Checkout.” Each numbered step in the diagram coincides with what this guide refers to as
Express Checkout Integration Points 1, 2, and 3.
The Integration Points occur in the following sequence. Your customer always starts and
completes his order on your website.
1. When a customer clicks Checkout with PayPal, he is transferred to PayPal to log in.
2. The customer then selects a shipping address and payment method and approves the use of
PayPal.
3. PayPal then returns the customer to your website to review and finalize the order.
FIGURE 2.1 Generalized Customer Checkout
At each Integration Point, you must set certain required API element values, and you can
affect the behavior and usefulness of Express Checkout by setting optional elements.
How Express Checkout Works
24 July 2006 Website Payments Pro Integration Guide
After a succinct description of the technical view of implementing Express Checkout, the
remainder of this chapter includes detailed steps for each of the Integration Points.
Express Checkout gives you the flexibility to put PayPal either first in your checkout process
or on your billing page along with other payment options.
TABLE 2.1 Steps in Integrating Express Checkout
Step Description See Page
1a After selecting products to purchase, your customer clicks the
Checkout with PayPal button on your website.
This allows your customer to quickly skip entering shipping and
billing information on your website.
28
1b Integration Point 1
You make an API call to pass PayPal the transaction details.
You then transfer the customer to PayPal via an HTTP redirect.
Your customer is transferred to PayPal.
29
2a Your customer selects a shipping address and payment method stored
on PayPal.
34
2b Your customer clicks Continue Checkout to approve the use of
PayPal and is returned to your website.
36
2c Integration Point 2
Your customer is transferred back to your website.
PayPal transfers the customer via an HTTP redirect. You then make an
API call to retrieve transaction details, such as shipping address, email
address, and other information needed to fulfill your order.
36
3a Your customer finishes the checkout process on your website, reviews
the order, and completes the order.
39
3b Integration Point 3.
When your customer places the order, you make an API call to PayPal
to request payment. (Your customer does not see this step.)
The payment transaction is initiated, and PayPal sends your customer
an email receipt for the payment.
41
4 You transfer your customer to your order confirmation page. 44
Website Payments Pro Integration Guide July 2006 25
How Express Checkout Works
Express Checkout Integration Points: Technical View
Express Checkout I nt egrat i on Poi nts: Techni cal Vi ew
A technical view of implementing Express Checkout is shown in Figure 2.2, “Express
Checkout Integration Points: Technical View” on page 26:
1. Preparatory indication to PayPal that you intend to use Express Checkout for the payment
for the customer’s order: SetExpressCheckoutRequest.
2. Getting details from PayPal about this customer (such as shipping address) and optionally
allowing the customer to edit these details during the order review:
GetExpressCheckoutDetailsRequest.
3. Making the payment transaction at the end of checkout, whether as the complete amount of
the sale or as an authorization for a total amount that you must later process with
Authorization & Capture: DoExpressCheckoutPaymentRequest.
For precise details about the elements in all three SOAP requests and responses, see Chapter 6,
“Express Checkout API.”
How Express Checkout Works
Express Checkout Integration Points: Technical View
26 July 2006 Website Payments Pro Integration Guide
FIGURE 2.2 Express Checkout Integration Points: Technical View
!
0
)

C
L
I
E
N
T
!
0
)

C
L
I
E
N
T
!
0
)

C
L
I
E
N
T
P
a
y
P
a
l

w
e
b

S
e
r
v
i
c
e
s


A
P
|

S
e
r
v
i
c
e
#
H
E
C
K
O
U
T
P
a
y
P
a
l

w
e
b

S
e
r
v
i
c
e
s


A
P
|

S
e
r
v
i
c
e
P
a
y
P
a
l

w
e
b

S
e
r
v
i
c
e
s


A
P
|

S
e
r
v
i
c
e
#
H
E
C
K
O
U
T
W
I
T
H

0
A
Y
0
A
L
s
e
l
e
c
t

f
u
n
d
i
n
g

s
o
u
r
c
e
s
e
l
e
c
t

s
h
i
p
p
i
n
g

a
d
d
r
e
s
s
#
A
N
C
E
L
2
E
T
U
R
N

T
O
-
E
R
C
H
A
N
T
/
R
D
E
R

R
E
V
I
E
W
P
A
G
E
%
D
I
T
0
A
Y
4
H
A
N
K

Y
O
U

F
O
R
Y
O
U
R

O
R
D
E
R

D
o
L
x
p
r
e
s
s
C
h
e
c
k
o
u
t
P
a
y
m
e
n
t
P
e
q
u
e
s
t
T
o
k
e
n
<
P
a
y
m
e
n
t
A
c
t
i
o
n
>
S
a
l
e
<
/
P
a
y
m
e
n
t
A
c
t
i
o
n
>





















r
e
s
p
o
n
s
e
T
r
a
n
s
a
c
t
i
o
n
I
D
P
a
y
m
e
n
t
I
n
f
o
|
f


<
P
a
y
m
e
n
t
A
c
t
i
o
n
>
A
u
t
h
o
r
i
z
a
t
i
o
n

R
U

O
r
d
e
r
<
/
P
a
y
m
e
n
t
A
c
t
i
o
n
>
"
R
O
W
S
E
R

R
E
D
I
R
E
C
T

T
O
V
A
L
U
E
/
F
2
E
T
U
R
N
5
2
,
&
t
o
k
e
n
¬
V
A
L
U
E
"
R
O
W
S
E
R

R
E
D
I
R
E
C
T

T
O
h
t
t
p
s
.
/
/
w
w
w
.
p
a
y
p
a
l
.
c
o
m
/
c
g
i
-
b
i
n
/
w
e
b
s
c
r
?
c
m
d
¬
_
e
x
p
r
e
s
s
-
c
h
e
c
k
o
u
t
&
t
o
k
e
n
¬
V
A
L
U
E
3
2
l
r
e
s
p
o
n
s
e
P
a
y
e
r
I
D
P
a
y
e
r
I
n
f
o
G
e
t
L
x
p
r
e
s
s
C
h
e
c
k
o
u
t
D
e
t
a
i
l
s
P
e
q
u
e
s
t
T
o
k
e
n
r
e
s
p
o
n
s
e
T
o
k
e
n
S
e
t
L
x
p
r
e
s
s
C
h
e
c
k
o
u
t
P
e
q
u
e
s
t
O
r
d
e
r
T
o
t
a
l
M
a
x
A
m
o
u
n
t
R
e
t
u
r
n
U
R
L
C
a
n
c
e
l
U
R
L
,
O
G
I
N

T
O

0
A
Y
0
A
L
P
a
y
P
a
l
A
u
t
h
o
r
i
z
a
t
i
o
n

&

C
a
p
t
u
r
e
P
r
o
c
e
s
s
Website Payments Pro Integration Guide July 2006 27
How Express Checkout Works
Express Checkout Integration Points: Technical View
TABLE 2.2 Express Checkout Program Flow-of-Control and Integration Points
Customer... Merchant... PayPal...
1 Clicks
Checkout
with PayPal
button.
Sends SOAP request SetExpressCheckoutRequest
with the required elements – estimated OrderTotal,
ReturnURL, and CancelURL – and optional elements, such
as MaxAmount.
Returns
SetExpressCheckoutResponse
with Token and appends the values of
Token and PayerID to your return URL.
Adds value of element Token from
SetExpressCheckoutRequest as a name/value pair
to the following URL, and redirects the user’s browser to it:
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=value
2 Logs in to
PayPal,
approves the
use of
PayPal, and
clicks
Continue
Checkout.
With a GET, redirects user’s browser to
merchant’s ReturnURL with token value
appended.
Sends SOAP request
GetExpressCheckoutDetailsRequest with
Token to retrieve your customer’s information.
Returns
GetExpressCheckoutDetailsRes
ponse with PayerID, email address,
shipping address, confirmed or
unconfirmed status of that shipping address,
and other details.
Renders page in customer’s browser for the next step in
checkout process, such as your “Order Review” page.
3 Clicks
“Confirm
Order”
button
Sends SOAP request
DoExpressCheckoutPaymentRequest with the
required elements Token, OrderTotal, PaymentAction,
and PayerID returned by
GetExpressCheckoutDetailsResponse.
Returns PaymentInfo with important
TransactionID value and other details
about the payment.
How Express Checkout Works
Relationship to Authorization & Capture
28 July 2006 Website Payments Pro Integration Guide
Rel at i onshi p t o Authorization & Capture
PayPal assumes that at the end of the checkout process, you will make a final sale and payment
transaction via PayPal. If at point of sale you do not know the complete cost of the order—for
example, if shipping, handling, and tax is not precisely known, or if you want to upsell—you
can authorize a transaction that you capture later with Authorization & Capture.
For more information about Authorization & Capture, see Chapter 4, “How Authorization &
Capture Works.”
Step 1a: Customer Selects PayPal on Your Website
PayPal recommends that you place the Express Checkout button on your website before your
customers are required to enter their shipping and billing information, as shown in Figure 2.3,
“PayPal Express Checkout Button Before Shipping Address Information.”
FIGURE 2.3 PayPal Express Checkout Button Before Shipping Address Information
Website Payments Pro Integration Guide July 2006 29
How Express Checkout Works
Step 1b: Integration Point 1
NOTE: Your customer always reviews transaction details and makes the final payment on your
website. PayPal handles the payment verification and passes you the customer’s
shipping information. PayPal never shares your customer’s financial information with
anyone.
Step 1b: Integration Point 1
As shown in Figure 2.4, “Express Checkout Integration Point 1,” Integration Point 1 is where
you transfer a customer’s browser to PayPal to select or add a shipping address and funding
source.
FIGURE 2.4 Express Checkout Integration Point 1
Integration Point 1 consists of the following events and actions:
z The customer clicks the Checkout with PayPal button.
z You send SetExpressCheckoutRequest to PayPal.
z PayPal returns the SetExpressCheckoutResponse.
z You redirect the customer’s browser to PayPal.
Usage Notes About SetExpressCheckout Elements
The following is important usage information about some of the required or optional elements
in the first SOAP request for Express Checkout. For complete details about all elements, see
“SetExpressCheckout” on page 76.
For information about suggested use of elements related to shipping address information, see
“Sending Shipping Address Information to PayPal” on page 65.
How Express Checkout Works
Step 1b: Integration Point 1
30 July 2006 Website Payments Pro Integration Guide
TABLE 2.3 SetExpressCheckoutRequest Usage Notes
Element
Required
or
Optional? Notes
OrderTotal Required The total estimated cost of the order to the customer.
If shipping and tax charges are known, include them in
OrderTotal; if not, OrderTotal should be the current subtotal of
the order.
MaxAmount Optional The expected maximum total amount of the complete order, including
shipping and tax charges.
PayPal uses an adjusted OrderTotal to determine which funding
sources it can authorize for use by the customer. PayPal business logic
calculations account for the fact that shipping and tax will likely be
added to the OrderTotal before the customer completes the
purchase. MaxAmount is additional information for PayPal’s business
logic to properly calculate the customer’s available funds for your
unique circumstances.
If OrderTotal is the final amount, set MaxAmount equal to
OrderTotal.
NOTE: If the final OrderTotal sent with the
DoExpressCheckoutPaymentRequest (the final
PayPal Express Checkout API) exceeds the value of
MaxAmount, the payment will still be successfully processed.
ReturnURL Required URL to which the customer’s browser is returned after approving use
of PayPal.
PayPal recommends that the value of the required ReturnURL
element be the final review page on which the customer confirms the
order and payment.
The value of your ReturnURL must always assume GET as the
FORM METHOD, just as if the value were to be included in a FORM.
That is, your ReturnURL must expect to read from the
QUERY_STRING environment variable, not from standard input.
For your programmatic control on the redirect of the customer’s
browser to your website, the value of ReturnURL can include any
name/value pairs your programs require.
Website Payments Pro Integration Guide July 2006 31
How Express Checkout Works
Step 1b: Integration Point 1
CancelURL Required URL to which the customer is returned if he decides not to use PayPal
or if PayPal is not able to authorize the customer.
PayPal recommends that the value of the required CancelURL be the
original page on which the customer chose to use PayPal. For instance,
if the customer were transferred to PayPal from your shipping
information page, the CancelURL value should be the URL of your
shipping information page. If the customer clicks Cancel on the
PayPal website, PayPal redirects the customer’s browser to your
shipping information page, where the customer can continue with your
standard checkout process.
PaymentAction Optional How you want to obtain payment:
z Sale indicates that this is a final sale for which you are
requesting payment.
z Authorization or Order indicate that this payment is subject
to settlement with PayPal Authorization & Capture. A
PaymentAction of Authorization indicates to PayPal that
the order total at the end of the customer’s checkout will not be a
final sale. If you choose this action, you will need to perform an
additional step in order to capture the payment.
IMPORTANT: You cannot set PaymentAction to Sale or
Order on SetExpressCheckoutRequest and then
change PaymentAction to Authorization on the final
PayPal Express Checkout API
DoExpressCheckoutPaymentRequest.
For more information about PayPal Authorization & Capture, see the
Chapter 4, “How Authorization & Capture Works.”
TABLE 2.3 SetExpressCheckoutRequest Usage Notes
Element
Required
or
Optional? Notes
How Express Checkout Works
Step 1b: Integration Point 1
32 July 2006 Website Payments Pro Integration Guide
cpp-header-
image
Optional A URL for the image you want to appear at the top left of the payment
page. The image has a maximum size of 750 pixels wide by 90 pixels
high.
IMPORTANT: PayPal recommends that you provide an
image from a secure (https) server. If the image is not
on a secure server, when the customer’s browser is
redirected to the PayPal website, the customer will see
a message about potential security risks (a mixture of
secure and insecure items). This message might
intimidate some customers from continuing with their
purchase.
In Figure 2.5, “PayPal Login Page” on page 34, the
DesignerFotos image beneath the PayPal logo demonstrates how a
cpp-header-image appears.
For more information about custom payment pages, see the Website
Payments Standard Integration Guide.
Custom Optional The optional Custom element is a passthrough variable. Its value is
returned verbatim on the final PayPal Express Checkout API,
DoExpressCheckoutPaymentResponse. You can use this
value for whatever purpose you desire, such as an accounting tracking
number or additional data needed by your programs (for example, a
session-id or other variable).
TABLE 2.4 SetExpressCheckoutResponse Usage Notes
Element Notes
Token A timestamped token by which you identify to PayPal that you are processing this
payment with Express Checkout.
NOTE: The token expires after three hours.
TABLE 2.3 SetExpressCheckoutRequest Usage Notes
Element
Required
or
Optional? Notes
Website Payments Pro Integration Guide July 2006 33
How Express Checkout Works
Step 1b: Integration Point 1
Transferring Your Customer to PayPal
After you receive a successful response from PayPal, you should add the value of the Token
from SetExpressCheckoutResponse as a name/value pair to the following URL, and
redirect your customer’s browser to it:
https://www.paypal.com/cgi-
bin/webscr?cmd=_express-checkout&token=value_from_SetExpressCheckoutResponse
Express Checkout has a varition on this redirect URL that allows you to bypass calling the
second API, GetExpressCheckoutDetails. See “Allow the Customer to Confirm Before
Calling DoExpressCheckoutPayment” on page 70.
Recommendation for Browser Redirection
For redirecting the customer’s browser to the PayPal URL, PayPal recommends that you use
the HTTPS response 302 “Object Moved” with your URL 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.
How Express Checkout Works
Step 2a: Customer Approves Use of PayPal
34 July 2006 Website Payments Pro Integration Guide
St ep 2a: Cust omer Approves Use of PayPal
The next step after redirecting the customer’s browser to PayPal with the response token is for
the customer to approve PayPal as the payment method for his purchase. The customer is
redirected to the PayPal login page to enter his email and password as shown in Figure 2.5,
“PayPal Login Page.” If the customer does not have a PayPal account, he can click the Don’t
have a PayPal account? Click Here link and enter his credit card information to register for a
PayPal account.
FIGURE 2.5 PayPal Login Page
If the customer has previously been to PayPal, his email address is pre-filled to save time
during login.
After the customer logs in to PayPal, he needs to verify his information on the “Review Your
PayPal Information” page, as shown in Figure 2.6, “PayPal Review Page.”
Website Payments Pro Integration Guide July 2006 35
How Express Checkout Works
Step 2a: Customer Approves Use of PayPal
FIGURE 2.6 PayPal Review Page
The customer then:
1. Can review his default funding source and shipping address, select other funding sources or
shipping address already saved on PayPal, or enter new ones.
NOTE: PayPal returns your customer to the ReturnURL specified by you in
SetExpressCheckoutRequest. If the customer clicks the Cancel button,
PayPal returns him to the CancelURL specified in the
SetExpressCheckoutRequest.
2. Clicks Pay to approve the use of PayPal.
3. Returns to your website to complete the purchase.
How Express Checkout Works
Step 2b: Customer Returns to Your Website
36 July 2006 Website Payments Pro Integration Guide
Step 2b: Customer Returns to Your Website
After the customer has selected shipping and billing information on the PayPal website, he
clicks Pay, which is the customer’s approval of the use of PayPal. PayPal then redirects the
customer’s browser to your website as described in “Step 2c: Integration Point 2.”
Step 2c: Integration Point 2
Figure 2.7, “Express Checkout Integration Point 2” illustrates Express Checkout Integration
Point 2.
FIGURE 2.7 Express Checkout Integration Point 2
Integration Point 2 consists of the following events and actions:
z The customer clicks Continue Checkout on the PayPal review screen.
z PayPal transfers your customer to the location you specified in the ReturnURL.
z You send the GetExpressCheckoutDetailsRequest to PayPal.
z PayPal returns the GetExpressCheckoutDetailsResponse.
z You display the next screen of your checkout process to your customer.
After your customer has reviewed and approved his financial and shipping information, and
done any necessary editing, PayPal redirects his browser to the ReturnURL provided in
SetExpressCheckoutRequest.
Website Payments Pro Integration Guide July 2006 37
How Express Checkout Works
Step 2c: Integration Point 2
ReturnURL, CancelURL, and the Express Checkout Token
PayPal appends the name/value pair token=tokenValue to the value of your ReturnURL and
CancelURL. For example, if you set ReturnURL as follows:
https://www.newco.com/ourcheckout
PayPal changes the value as follows:
https://www.newco.com/ourcheckout?token=tokenValue
Similarly, if your ReturnURL value already has name/value pairs, like the following:
https://www.newco.com/ourcheckout?cartid=1234
PayPal prefixes the appended token with the name/value pair delimiter, like this:
https://www.newco.com/ourcheckout?cartid=1234&token=tokenvalue
Once the customer arrives at this ReturnURL, you need to send the
GetExpressCheckoutDetailsRequest with the Token value provided in
SetExpressCheckoutResponse. PayPal then sends you a response with your customer’s
transaction information.
For a list of all elements in GetExpressCheckoutDetailsResponse, see
“GetExpressCheckoutDetailsResponse” on page 84.
Usage Notes About GetExpressCheckoutDetails Elements
The following outlines usage information for some of the important elements sent in this
response.
TABLE 2.5 GetExpressCheckoutDetailsResponse Usage Notes
Element Notes
Payer Email address of the payer.
PayerID Unique PayPal customer account number.
You must provide this value with
DoExpressCheckoutPaymentRequest.
PayerStatus The payer’s PayPal account status.
A value of Verified means that the customer has confirmed ownership of a
bank account or has verified his account status through other means.
FirstName
LastName
The payer’s name.
How Express Checkout Works
Step 2c: Integration Point 2
38 July 2006 Website Payments Pro Integration Guide
To protect the privacy of your customer, PayPal does not share billing address or financial
information, such as credit card numbers.
NOTE: The terms of PayPal’s Privacy Policy allow you to use a customer’s personal
information only for communications relating to the transaction, unless the customer
expressly gives you permission to use the information for other purposes. For
information about the PayPal Privacy Policy, see http://www.paypal.com/privacy.
Address The payer’s shipping address selected on PayPal.
NOTE: With SetExpressCheckoutRequest, if you sent PayPal an
Address in and set AddressOverride, on
GetExpressCheckoutDetailsResponse PayPal returns the
shipping address you originally sent on
SetExpressCheckoutRequest.
For the recommended use of elements on
SetExpressCheckoutRequest for handling shipping address
information that the customer enters on your website (not on PayPal), see
“Sending Shipping Address Information to PayPal” on page 65.
AddressStatus The status of the customer’s shipping address.
A status of Confirmed means that the shipping address matches a billing
address on record with PayPal and that that billing address has been verified by
AVS. Your use of a Confirmed address is one of the requirements for you to
be protected by PayPal’s Seller Protection Policy (SPP). For more information
about the Seller Protection Policy, see the following:
https://www.paypal.com/spp
ContactPhone Payer’s contact telephone number.
ContactPhone is returned to you only if you set this as a preference in the
Website Payment Preferences of your Profile on https://www.paypal.com.
TABLE 2.5 GetExpressCheckoutDetailsResponse Usage Notes
Element Notes
Website Payments Pro Integration Guide July 2006 39
How Express Checkout Works
Step 3a: Customer Completes Order
St ep 3a: Cust omer Compl et es Order
After you receive a successful GetExpressCheckoutDetailsResponse, display the next
page in your checkout process. This page might be your order review page or a page on which
the customer can select a shipping method, enter shipping instructions, or specify any other
information necessary to complete the purchase.
FIGURE 2.8 Example of Order Review Page
PayPal recommends that you alter your order review page as follows. Figure 2.8, “Example of
Order Review Page” on page 39 is an example of a page that has been altered to reflect these
guidelines.
How Express Checkout Works
Step 3a: Customer Completes Order
40 July 2006 Website Payments Pro Integration Guide
When the customer clicks the “Place Order” button, send
DoExpressCheckoutPaymentRequest to initiate the payment. After a successful response
is sent from PayPal, direct the customer to your order completion page to inform him that you
received his order.
TABLE 2.6 Shipping, Billing and Order Total Usage
Shipping
Information Section
Display the shipping address supplied by PayPal.
The “Edit Shipping” button should return your customer to PayPal to edit shipping
information on the PayPal website. This allows the customer to quickly select a
different address that he already has stored with PayPal, or enter a new address. This
also ensures that PayPal can provide you with the updated AddressStatus for the new
shipping address.
For other recommendations about the design of your order review page, see “Edit
Shipping” on page 70.
For information about AddressStatus, see “AddressStatus” on page 86.
Billing Information
Section
For billing information, display the customer’s PayPal email address provided in
Express Checkout.
Order Total With Express Checkout, you must display to the customer the same exact OrderTotal
value that you send to PayPal in DoExpressCheckoutPaymentRequest.
Website Payments Pro Integration Guide July 2006 41
How Express Checkout Works
Step 3b: Integration Point 3
St ep 3b: I nt egrat i on Poi nt 3
Figure 2.9, “Express Checkout Integration Point 3” illustrates Express Checkout Integration
Point 3.
FIGURE 2.9 Express Checkout Integration Point 3
Integration Point 3 consists of the following events and actions:
z The customer clicks the “Place Order” button on your website.
z You send the DoExpressCheckoutPaymentRequest to PayPal.
z PayPal returns the DoExpressCheckoutPaymentResponse.
z You redirect the customer to your “Order Confirmation” page.
Usage Notes About DoExpressCheckoutPaymentRequest Elements
The following are important usage information about some of the required or optional
elements in the final SOAP request for Express Checkout.
How Express Checkout Works
Step 3b: Integration Point 3
42 July 2006 Website Payments Pro Integration Guide
TABLE 2.7 DoExpressCheckoutPaymentRequest Usage Notes
Element
Required
or
Optional
? Notes
OrderTotal Required Total of the order, including shipping, handling, and tax. This must be
the final amount of the purchase and can differ from the original,
estimated OrderTotal you sent in the
SetExpressCheckoutRequest.
NOTE: PayPal does not enforce a maximum difference between the
original estimated OrderTotal and the one you send on
DoExpressCheckoutPaymentRequest . However, if
the difference is substantial, your customer may no longer be
approved to use the funding source he originally accepted.
PaymentAction Required How you want to obtain payment:
z Sale indicates that this is a final sale for which you are
requesting payment.
z Authorization or Order indicate that this payment is subject
to settlement with PayPal Authorization & Capture.
NOTE: If you set PaymentAction to Sale or Order on
SetExpressCheckoutRequest, you cannot change the
PaymentAction value on
DoExpressCheckoutPaymentRequest.
You can, however, set PaymentAction to Sale on
DoExpressCheckoutPaymentRequest if you
originally set it to Authorization on
SetExpressCheckoutRequest.
IMPORTANT: PayPal requires that a merchant using
Express Checkout display to the customer the same
amount that the merchant sends to PayPal for initial
authorization in the OrderTotal element with the
DoExpressCheckoutPaymentRequest API.
ItemTotal
ShippingTotal
HandlingTotal
TaxTotal
Optional You can send individual order-level totals for items, shipping,
handling, and tax. If you send this information, PayPal includes it in
the customer’s transaction receipt from PayPal and on PayPal’s
Transaction Details page.
If you send this information, the sum of these four totals must equal
OrderTotal.
Website Payments Pro Integration Guide July 2006 43
How Express Checkout Works
Step 3b: Integration Point 3
Order
Description
Optional The description you want to appear on the customer’s transaction
receipt from PayPal and on PayPal’s Transaction Details page.
PayPal recommends that you include your order number for this
purchase if one is available.
PaymentItem
z Name
z Number
z Amount
z Quantity
z SalesTax
Payment
Details
z ItemTotal
z TaxTotal
Payment
Item is
optional
.
Payment
Details
is
required.
If you send details about each item, they are included in the customer’s
transaction receipt from PayPal and on PayPal’s Transaction Details
page.
Providing this information allows your customer to review the
purchase information in his PayPal account details, can remind your
customer about the purchase details, and might decrease the likelihood
that your customer will mistakenly file a chargeback.
The following rules apply to the PaymentItem elements:
1. If you send PaymentItem.Name, you must also send
PaymentItem.Amount.
2. If you send PaymentItem.Amount, the sum of
(PaymentItem.Amount x Quantity) for all payment items
must equal PaymentDetails.ItemTotal.
3. If you send PaymentItem.SalesTax, the sum of
(PaymentItem.SalesTax x Quantity) for all payment items
must equal PaymentDetails.TaxTotal.
ShipToAddress Optional If you allow the customer to enter or edit shipping information on your
website, you should pass your customer’s shipping address to PayPal.
IMPORTANT: If you are using the shipping address PayPal
returned to you with
GetExpressCheckoutDetailsResponse, do not
pass this address back to PayPal on
DoExpressCheckoutPaymentRequest.
NOTE: PayPal recommends that, whenever possible, you allow your
customer to use the shipping address stored by PayPal.
Doing so helps your customer complete the checkout more
quickly and allows PayPal to provide you with the shipping
AddressStatus in
GetExpressCheckoutDetailsResponse.
TABLE 2.7 DoExpressCheckoutPaymentRequest Usage Notes
Element
Required
or
Optional
? Notes
How Express Checkout Works
Step 4: Customer Notified Order Is Complete
44 July 2006 Website Payments Pro Integration Guide
St ep 4: Cust omer Not i f i ed Order I s Compl et e
After the customer approves the order and it completes successfully, PayPal recommends that
you display an order completion page showing the details of the transaction. An example is
shown below.
FIGURE 2.10Example of Order Complete Page
PayPal sends the customer an email notification with the completed transaction details of the
order. You also receive an email of the payment and can view it in your Downloadable History
Log or Account Overview.
Website Payments Pro Integration Guide July 2006 45
3
How Direct Payment API Works
PayPal Direct Payment API offers you direct credit card payment processing through PayPal.
To pay with a credit card, your customer never leaves your website, as PayPal processes the
payment behind the scene.
FIGURE 3.1 Generalized Customer Checkout with Direct Payment API
TABLE 3.1 Steps in Checkout with Direct Payment API
Step Description
1 On your website, the customer chooses to pay with a credit card and
enters the credit card number and other details.
2 The customer reviews the order.
3 When your customer clicks “Pay” to place the order, you call a PayPal
API to request payment, and the payment transaction is initiated.
NOTE: The customer does not see this step. PayPal does not send
your customer a recipt for the payment.
4 You transfer your customer to your order confirmation page.
How Direct Payment API Works
Technical Overview
46 July 2006 Website Payments Pro Integration Guide
Techni cal Overvi ew
At the point of payment in the checkout process, the “Pay” button on your website must send
the DoDirectPaymentRequest to the PayPal Web Services API service, including required
information you collected from the customer, such as the amount of the transaction, the
buyer’s credit card number, expiration date, browser IP address, and an element that specifies
whether this transaction is a final sale (complete transaction amount including shipping,
handling and tax) or an authorization for a final amount that you must capture later with
Authorization & Capture. The Direct Payment API SOAP response includes a transaction
identification number and other information.
FIGURE 3.2 PayPal Direct Payment Integration Point: Technical View
PayPal is completely invisible to your customer, before, during, and after the purchase. PayPal
does not send an email receipt to the customer, nor will the customer’s credit card statement
indicate that PayPal processed th epayment.
For more details about the Direct Payment API, see Chapter 7, “Direct Payment API.”
IMPORTANT: Direct Payment API is not a standalone product. You are required to use
Direct Payment and Express Checkout together as part of the Website
Payments Pro solution. For information about these business rules, see
Chapter 5, “Design Choices for Best Buying Experience.”
!0)CLIENT
PayPal web Services
AP| Service
0AY
4HANKYOUFOR
YOURORDER
DoDirect
Payment Pequest
CreditCard
<PaymentAction>Sale</PaymentAction>
PayPal
Authorization & Capture
Process
response
TransactionID
PaymentInfo
|f <PaymentAction>
Authorization
</PaymentAction>
/RDERREVIEW
PAGE
Website Payments Pro Integration Guide July 2006 47
How Direct Payment API Works
Relationship to Authorization & Capture
Relationship to Authorization & Capture
PayPal assumes that at the end of the checkout process, you will make a final sale and payment
transaction via PayPal. If at point of sale you do not know the complete cost of the order—for
example, if shipping, handling, and tax is not precisely known, or if you want to upsell—you
can authorize a transaction that you capture later with Authorization & Capture.
For more information about Authorization & Capture, see the Authorization & Capture
Integration Guide.
How Direct Payment API Works
Relationship to Authorization & Capture
48 July 2006 Website Payments Pro Integration Guide
Website Payments Pro Integration Guide July 2006 49
4
How Authorization & Capture
Works
Authorization & Capture is a settlement solution that provides merchants increased flexibility
in obtaining payments from their buyers. During a traditional sale at PayPal, the authorization
and capture action is completed simultaneously. Authorization & Capture separates the
authorization of payment from the capture of the authorized payment.
Authorization & Capture is for merchants who have a delayed order fulfillment process and
who typically make a $1 auth at checkout. It enables merchants to modify the original
authorization amount due to order changes occurring after the initial order is placed (such as
taxes, shipping, or item availability). This chapter discusses the authorization and capture
process and provides steps to help you authorize, capture, reauthorize, and void funds.
There are two ways to use Authorization & Capture:
1. Use the Authorization & Capture Application Programming Interface (API), which is
discussed here.
2. Create an order or authorization with Website Payments Standard HTML and capture or
void the authorization on the PayPal website (https://www.paypal.com/). This topic is not
discussed here. For more information about the Authorization & Capture and Website
Payments Standard, see the Website Payments Standard Integration Guide
How Authorization & Capture Works
Fundamental Authorization Process With the APIs
50 July 2006 Website Payments Pro Integration Guide
Fundamental Aut hori zat i on Process Wi t h t he API s
The fundamental process for authorizing and capturing is shown below.
FIGURE 4.1 Fundamental Authorization & Capture Process with APIs
Authorization & Capture starts when your buyer authorizes a payment amount during
checkout.
1. For example, you can use the PayPal Express Checkout API with the <PaymentAction>
element set to Authorization or Order.
Similarly, you can use the Direct Payment API with the <PaymentAction> element set
to Authorization. Currently, the Direct Payment API does not support order
authorizations.
2. After your buyer completes checkout, you can then use the payment’s transaction ID with
Authorization & Capture APIs. You can:
z Capture either a partial amount or the full authorization amount.
z Authorize a higher amount, up to 115% of the originally authorized amount (not to exceed
an increase of $75 USD).
z Void a previous authorization.
Honor Period and Authorization Period
When your buyer approves an authorization, the buyer’s balance can be placed on hold for a
29-day period to ensure the availability of the authorization amount for capture. You can
reauthorize a transaction only once, up to 115% of the originally authorized amount (not to
exceed an increase of $75 USD).
1
DoExpressCheckout
PaymentRequest
<PaymentAction>
Authorization
or
Order
</PaymentAction>
2 3 4 1
PayPal Web Services API Service
Basic or Order Authorizations:
DoReauthorization
Response
DoReauthorization
Request
DoVoid
Response
DoVoid
Request
DoAuthorization
Request
DoAuthorization
Response
response
DoCapture
Request
DoCapture
Response
Merchant API Client
for order auth for basic auth
Website Payments Pro Integration Guide July 2006 51
How Authorization & Capture Works
Fundamental Authorization Process With the APIs
After a successful reauthorization, PayPal honors 100% of authorized funds for three days. A
day is defined as the start of the calendar day on which the authorization or reauthorization
was made (from 12AM PST to 11:50PM PST).
You can settle without a reauthorization from day 4 to day 29 of the authorization period, but
PayPal cannot ensure that 100% of the funds will be available after the three-day honor period.
However, PayPal will not allow you to capture funds if the buyer’s account is restricted,
locked, or a fraudulent case occurs, or if your account has a high restriction level. You can use
Authorization & Capture only when your account has a low restriction level.
The honor period and authorization period for authorizations is described below:
If you attempt to capture funds outside the honor period, PayPal applies best efforts to capture
funds. However, there is a possibility that funds will not be available at that time.
Buyer and seller accounts cannot be closed if there is a pending (unsettled) authorization.
Supported PayPal Payment Products
You can use Authorization & Capture with the PayPal products listed in Table 4.1, “PayPal
Products Supporting Authorization & Capture.”
By default, these products assume that a transaction is a final sale. You must explicitly specify
that a transaction is a basic or order authorization.
NOTE: You must capture and void orders and order authorizations using the Authorization &
Capture APIs. That is, you cannot process order authorizations on the PayPal website
(https://www.paypal.com). The PayPal website supports processing only basic
authorizations, not order authorizations.
PayPal Products Not Supported
Authorization & Capture cannot be used with the following products:
z eBay checkout
z eCheck
z Gift Certificates and Coupons
z Subscriptions
TABLE 4.1 PayPal Products Supporting Authorization & Capture
Product Typical Usage
Website Payments paymentaction=”authorization”
Buy Now paymentaction=”authorization”
Donations paymentaction=”authorization”
Shopping carts paymentaction=”authorization”
How Authorization & Capture Works
Order Authorizations Scenarios
52 July 2006 Website Payments Pro Integration Guide
z Instant Purchase
z Send Money
z Request Money
z Virtual Terminal
z Invoicing
Order Authorizations Scenarios
The following are common scenarios you will encounter when implementing order
authorizations.
Simple Order
TABLE 4.2 Simple Order Scenario
Complex Order
TABLE 4.3 Complex Order Scenario
Action API Call Running Balance
Your buyer orders an item from your
website.
You request an order from PayPal to
authorize the payment, specifying the
variable paymentaction=order. You
receive a response that the order has been
created for a payment amount of $100.00.
DoExpressCheckoutPaymentRequest
with:
<PaymentAction>
order
</PaymentAction>
You request authorization for $100.00. DoAuthorizationRequest <$100.00>
You capture funds in the amount of
$115.00, the maximum amount allowed.
The order now has a “Complete” status.
DoCaptureRequest $15.00
Action API Call Running Balance
Your buyer orders 2 items from your
website.
Website Payments Pro Integration Guide July 2006 53
How Authorization & Capture Works
Order Authorizations Scenarios
Concurrent Authorizations
TABLE 4.4 Concurrent Authorizations Scenario
You request an order from PayPal to
authorize the payment, specifying the
variable paymentaction=order. You
receive a response that the order has been
created for a payment amount of $100.00.
DoExpressCheckoutPaymentRequest
with:
<PaymentAction>
order
</PaymentAction>
You request authorization #1 for $75.00. DoAuthorizationRequest <$75.00>
Your buyer contacts you and upgrades to
next-day shipping. You capture funds in
the amount of $80.00 on authorization #1
to accomodate for the additional shipping
charges.
DoCaptureRequest $5.00
You request authorization #2 for $25.00. DoAuthorizationRequest <$25.00>
Your buyer contacts you and changes an
item on the order. You void authorization
#2.
DoVoid $0.00
You request authorization #3 for $35.00
for the new item selection.
DoAuthorizationRequest <$35.00>
You capture authorization #3 for $35.00.
Because the maximum amount of funds
that can be captured has been reached
(115% of the original order amount), the
order now has a “Complete” status.
DoCaptureRequest $0.00
Action API Call Running Balance
Your buyer orders 3 pieces of equipment
for $300.00 from your website.
You request an order from PayPal to
authorize the payment, specifying the
variable paymentaction=order. You
receive a response that the order has been
created for a payment amount of $300.00.
DoExpressCheckoutPaymentRequest
with:
<PaymentAction>
order
</PaymentAction>
You request authorization #1 on day 1 for
$100.00 for the keyboard. You receive a
response that the authorization has been
created for a payment amount of $100.00.
DoAuthorizationRequest <$100.00>
Action API Call Running Balance
How Authorization & Capture Works
Order Authorizations Scenarios
54 July 2006 Website Payments Pro Integration Guide
Total Capture Hits Relative Tolerance With Open Authorizations
TABLE 4.5 Total Capture Hits Relative Tolerance with Open Authroziations Scenario
Void Authorizations
You capture authorization #1 for $100.00.
You ship the keyboard.
DoCaptureRequest $0.00
You request authorization #2 on day 2 for
$200.00 for the second component. You
receive a response that the authorization
has been created for a payment amount of
$200.00.
DoAuthorizationRequest <$200.00>
On day 3, you capture authorization #2 for
$200.00.
DoCaptureRequest $0.00
You ship the second component.
Action API Call Running Balance
Your buyer orders an item from your
website for $1000.00.
You request an order from PayPal to
authorize the payment, specifying the
variable paymentaction=order. You
receive a response that the order has been
created for a payment amount of $1000.00.
DoExpressCheckoutPaymentRequest
with:
<PaymentAction>
order
</PaymentAction>
Your buyer requests overnight shipping.
You request authorization #1 for $1100.00
(110% relative tolerance).
DoAuthorizationRequest <$1100.00>
You receive a response that the
authorization has been created for a
payment amount of $1100.00. You ship
the in-stock item by overnight shipping.
You capture authorization #1 for
$1100.00.
DoCaptureRequest $0.00
Your buyer contacts you and adds another
item to the order. You request
authorization #2 for $60.00, increasing the
order total to $1160.00, which exceeds the
115% tolerance limit of the original order.
DoAuthorizationRequest <$60.00>
You receive a response that the request for
authorization #2 has been declined.
$0.00
Action API Call Running Balance
Website Payments Pro Integration Guide July 2006 55
How Authorization & Capture Works
Order Authorizations Scenarios
TABLE 4.6 Void Authorizations Scenario
Partial Capture
TABLE 4.7 Partial Capture Scenario
Action API Call Running Balance
Your buyer orders 2 items from your
website.
You request an order from PayPal to
authorize the payment, specifying the
variable paymentaction=order. You
receive a response that the order has been
created for a payment amount of $350.00.
DoExpressCheckoutPaymentRequest
with:
<PaymentAction>
order
</PaymentAction>
You request authorization #1 on day 1 for
$100.00. You receive a response that the
authorization has been created for a
payment amount of $100.00.
DoAuthorizationRequest <$100.00>
You ship the item. You capture
authorization #1 for $100.00.
DoCaptureRequest $0.00
You request authorization #2 on day 2 for
$200.00. You receive a response that the
authorization has been created for a
payment amount of $200.00.
DoAuthorizationRequest <$200.00>
The buyer contacts you and cancels the
remaining item.
You void authorization #2. DoVoid $0.00
Action API Call Running Balance
Your buyer orders an item from your
website.
You request an order from PayPal to
authorize the payment, specifying the
variable paymentaction=order. You
receive a response that the order has been
created for a payment amount of $100.00.
DoExpressCheckoutPaymentRequest
with:
<PaymentAction>
order
</PaymentAction>
.You request authorization #1 on day 1 for
$100.00. You receive a response that the
authorization has been created for a
payment amount of $100.00.
DoAuthorizationRequest <$100.00>
How Authorization & Capture Works
Optimal Buyer Experience
56 July 2006 Website Payments Pro Integration Guide
Complete Capture
TABLE 4.8 Complete Capture Scenario
NOTE: The default for the DoCapture API is a Complete capture, not a Partial capture.
Optimal Buyer Experience
This section details the best practices you should follow in using Authorization & Capture to
ensure the best buying experience for your customers and getting the most from Authorization
& Capture.
Capturing Funds on Basic Authorizations
PayPal recommends that you capture funds within the honor period of three days because
PayPal will honor the funds for a 3-day period after the basic authorization. If you attempt to
capture funds after the three-day period and the authorization fails, your request to capture
funds may be declined.
You ship the item. You capture
authorization #1 for $100.00.
DoCaptureRequest $0.00
With CompleteType set to NotComplete
on the DoCapture API, you capture funds
in the amount of $50.00.
DoCaptureRequest $50.00
Action API Call Running Balance
Your buyer orders an item from your
website.
You request an order from PayPal to
authorize the payment, specifying the
variable paymentaction=order. You
receive a response that the order has been
created for a payment amount of $100.00.
DoExpressCheckoutPaymentRequest
with:
<PaymentAction>
order
</PaymentAction>
You request authorization #1 on day 1 for
$100.00. You receive a response that the
authorization has been created for a
payment amount of $100.00.
DoAuthorizationRequest <$100.00>
You capture authorization #1 for $100.00.
You ship the item.
DoCaptureRequest $0.00
Action API Call Running Balance
Website Payments Pro Integration Guide July 2006 57
How Authorization & Capture Works
Optimal Buyer Experience
After day 4 of the authorization period, you can initiate a reauthorization, which will start a
new three-day honor period. However, it will not extend the original authorization period past
29 days. For example, if you successfully complete a reauthorization on day 29 of the
authorization period, funds will only be honored until the end of the 29th day, and a new three-
day honor period will start but not extend beyond day 29.
You should capture funds within 24 hours after you ship your buyer’s order.
Buyer Approval for Basic Authorizations
A buyer-initiated authorization allows you to capture funds from the buyer’s account up to
115% of the originally authorized amount (not to exceed an increase of $75 USD) and up to
$10,000 USD.
IMPORTANT: If you want to update any details of the purchase that change the original
authorization amount, PayPal requires that you obtain consent from the
buyer at the time of purchase or at the time of capture.
Voiding Basic Authorizations
You should void an authorization if the authorization or reauthorization will not be used.
Voiding the authorization unlocks the temporary hold placed on your buyer’s funding sources.
How Authorization & Capture Works
Optimal Buyer Experience
58 July 2006 Website Payments Pro Integration Guide
Website Payments Pro Integration Guide July 2006 59
5
Design Choices for Best Buying
Experience
You have a design choice for placing PayPal buttons on your website:
z Implementation Point A: The Express Checkout Shortcut implementation
with the button graphic at the beginning of checkout
Or
z Implementation Point B: The Express Checkout Mark implementation
with the button graphic before the end of checkout
FIGURE 5.1 Implementation Points A and B
Whether you choose implementation point A or B, you call the same Express Checkout APIs.
Design Choices for Best Buying Experience
Implementation Point A: Express Checkout Shortcut
60 July 2006 Website Payments Pro Integration Guide
Implementation Point A: Express Checkout Shortcut
Putting PayPal first in your checkout—the Express Checkout Shortcut implementation—
allows a customer to save time by skipping several checkout steps. This section details how to
position PayPal at the beginning of your checkout process.
Figure 5.2, “Example of Button Placement for Express Checkout Shortcut” on page 60 is an
example of how to implement the Express Checkout product as the first step of your checkout
process. By placing the button before your customer is asked to enter shipping and billing
information, your customer can check out quickly using information already stored on PayPal.
FIGURE 5.2 Example of Button Placement for Express Checkout Shortcut
Button Placement Business Rules for Express Checkout Shortcut
With the Express Checkout Shortcut implementation, adhere to the following four business
rules. Following these rules helps PayPal account holders understand that they are offered the
benefits of a faster checkout. In addition, this placement can increase impulse purchases,
repeat purchases, and purchases from shoppers who are comfortable paying online only with
PayPal.
Add the PayPal choice at the top of the first page of your checkout process before you ask for
the shipping address or payment method.
Use the approved Express Checkout button
You can get the Express Checkout button logo and message text from the following location:
Website Payments Pro Integration Guide July 2006 61
Design Choices for Best Buying Experience
Implementation Point A: Express Checkout Shortcut
https://www.paypal.com/express-checkout-buttons
From this location, copy the HTML and paste it in the appropriate location of your checkout
pages, as described in “Implementation Point A: Express Checkout Shortcut” on page 60. You
might need to edit the variables in the HTML to suit your particular needs.
Put the text following text above either the Checkout with PayPal button or the
corresponding message, whichever is most appropriate to your website design.
Fast, Secure Checkout with PayPal
Put the following message next to the PayPal Express Checkout button:
Save time. Checkout securely. Pay without sharing your financial information.
Design Choices for Best Buying Experience
Implementation Point B: Express Checkout Mark
62 July 2006 Website Payments Pro Integration Guide
I mpl ementat i on Poi nt B: Express Checkout Mark
The Express Checkout Mark implementation is Step 1a in Figure 5.3, “Placement of Express
Checkout Mark Implementation.” This is the point in the checkout process where PayPal can
be placed with other payment methods.
FIGURE 5.3 Placement of Express Checkout Mark Implementation
An example of PayPal’s recommended placement of PayPal with other payment methods is
shown in Figure 5.4, “Example of Button Placement for Express Checkout Mark” on page 63.
For background information about design considerations similar to this, see “Step 1a:
Customer Selects PayPal on Your Website” on page 28. The primary difference is that the
customer selects PayPal from a list of other payment methods. When the customer clicks the
“Continue Checkout” button or hyperlink on your billing page, you must redirect the customer
to PayPal according the instructions described “Step 1b: Integration Point 1” on page 29.
Website Payments Pro Integration Guide July 2006 63
Design Choices for Best Buying Experience
Implementation Point B: Express Checkout Mark
FIGURE 5.4 Example of Button Placement for Express Checkout Mark
Design Choices for Best Buying Experience
Implementation Point B: Express Checkout Mark
64 July 2006 Website Payments Pro Integration Guide
Button Placement Business Rules for Express Checkout Mark
For the Express Checkout Mark implementation, when PayPal is positioned with other
payment methods, PayPal recommends the following design:
IMPORTANT: The positioning of Express Checkout according to these business rules is
required if you are implementing PayPal Direct Payment.
1. Display the options for payment methods before you ask the customer for billing address
information.
Add the PayPal mark logo graphic
as one of the options.
NOTE: You can find this logo graphic in the PayPal logo center at the following location:
https://www.paypal.com/logocenter
Add the following message next to the PayPal mark logo:
Save time. Checkout securely. Pay without sharing your financial information.
Make a design choice for the display of PayPal with other payment methods. You have several
designs to choose from:
– The treatment shown in “Example of Button Placement for Express Checkout Mark” on
page 63
– Horizontal option fields shown in Figure 5.5, “Payment Methods in Horizontal Design.”
– A drop-down SELECT list shown in Figure 5.6, “Payment Methods as Drop-Down
SELECT List..”
FIGURE 5.5 Payment Methods in Horizontal Design
FIGURE 5.6 Payment Methods as Drop-Down SELECT List
Treatment When PayPal Is Selected
When your customer selects PayPal, you should:
Use JavaScript to hide or disable credit card fields and billing address fields. Customers will
be confused if they are asked to enter this information after selecting PayPal.
Website Payments Pro Integration Guide July 2006 65
Design Choices for Best Buying Experience
Implementation Point B: Express Checkout Mark
If other fields such as coupon code or gift certificate are on the page, still display them so your
customer may fill them out before being redirected to PayPal.
Change the function of the “Continue Checkout” button to send the customer to PayPal
according to the instructions in “Step 1b: Integration Point 1” on page 29.
Near the “Continue” button or hyperlink, put an explanatory message such as the following to
inform your customer what will occur when the “Continue” button or hyperlink is clicked. The
text Your Company Name is the name of your business.
Clicking “Continue” will transfer you to PayPal. After you approve the use of PayPal, you will
be returned to Your Company Name to complete your purchase.
Figure 5.7, “Example of Billing Information Page with PayPal Selected” on page 65 shows
what your billing page might look like after the customer selects PayPal.
FIGURE 5.7 Example of Billing Information Page with PayPal Selected
Sending Shipping Address Information to PayPal
If you have already collected shipping address information from your customer, on the PayPal
pages the customer should be able to see this shipping address information but not be able to
change it. Follow these usage notes to send the shipping address to PayPal with
SetExpressCheckoutRequest.
Design Choices for Best Buying Experience
Implementation Point B: Express Checkout Mark
66 July 2006 Website Payments Pro Integration Guide
For complete details about SetExpressCheckoutRequest, see
“SetExpressCheckoutRequest” on page 77.
TABLE 5.1 SetExpressCheckoutRequest Usage Notes: Shipping Address
Element Notes
Address Customer’s street address for shipping.
Your sending the customer-entered shipping Address to PayPal allows PayPal
to return the address confirmation status in the AddressStatus element of
GetExpressCheckoutDetailsResponse. Be sure to include the
Country element as part of Address.
NOTE: The address entered by the customer on your website must exactly
match the customer’s confirmed PayPal address in order for PayPal to
verify that the shipping address is confirmed. Your use of a
Confirmed address is one of the requirements for you to be protected
by PayPal’s Seller Protection Policy (SPP). For more information
about the Seller Protection Policy, see the following:
https://www.paypal.com/spp
Address
Override
If you set AddressOverride, the Address sent on
SetExpressCheckoutRequest overrides the customer’s stored address.
The customer is shown the passed-in address but cannot edit it.
NOTE: If the Address is not valid (such as missing required fields, including
Country) or not included SetExpressCheckoutRequest,
PayPal does not display any address to the customer.
Website Payments Pro Integration Guide July 2006 67
Design Choices for Best Buying Experience
Best Buying Experience in Shortcut Implementation
Best Buyi ng Experi ence i n Short cut I mpl ementat i on
A key benefit of Express Checkout is that a customer can save time by skipping several
checkout steps using the shipping and billing information stored on PayPal. You might have to
adjust your checkout flow to avoid redundant information gathering from the customer, to
make sure you gather other important information from the customer that PayPal does not
supply, or to prevent “circular” pages.
This section details some best practices you should consider in implementing the Express
Checkout Shortcut.
Move Important Fields to End of Checkout
The pages your customer skips might ask for important information such as shipping method,
delivery date, or coupon codes. In this case, PayPal recommends that you collect this
information from your customer after the return to your website after Express Checkout
Integration Point 2. For instance, if you ask for shipping method on your shipping address
page, consider moving the fields to gather this information to your “Order Review” page. See
Figure 5.8, “Example of Optimal Order Review Page after Return from PayPal” and
Figure 5.10, “Example of Optimal Billing Page” on page 69.
FIGURE 5.8 Example of Optimal Order Review Page after Return from PayPal
Use the Information Returned by PayPal
If you prefer not to change your checkout flow as described in the previous section, PayPal
recommends that you return your customer to the original page where your important
information fields appear. Be sure to disable or hide your own shipping address, billing
address, and payment method fields, and display the information that PayPal supplies you.
Example of Optimal Customer Experience
The following is a detailed example.
Design Choices for Best Buying Experience
Best Buying Experience in Shortcut Implementation
68 July 2006 Website Payments Pro Integration Guide
If you position the PayPal button at the top of your shipping address page, after the customer
has clicked Continue Checkout on PayPal, return the customer to your shipping address page
(this URL is the value of ReturnURL.).
On your shipping address page, display the shipping address PayPal has provided in
GetExpressCheckoutDetailsResponse and display your shipping method input fields or
SELECT list so your customer can select the method. See Figure 5.9, “Example of Optimal
Shipping Method Page.”
FIGURE 5.9 Example of Optimal Shipping Method Page
When your customer clicks “Continue,” display your billing page. Show the payment method
as PayPal, and ask your customer to enter additional information, such as coupon codes. Do
not ask the customer for billing address at this point because he has indicated he is using
PayPal.
Website Payments Pro Integration Guide July 2006 69
Design Choices for Best Buying Experience
Best Buying Experience in Shortcut Implementation
FIGURE 5.10Example of Optimal Billing Page
Design Choices for Best Buying Experience
Best Buying Experience in Shortcut or Mark Implementations
70 July 2006 Website Payments Pro Integration Guide
Best Buyi ng Experi ence i n Short cut or Mark
I mpl ementat i ons
This section details some best practices you should consider in designing either the Express
Checkout Shortcut implementation or the Express Checkout Mark Implementation. These
practices apply to both implementations to give your customer the best shopping experience.
Allow the Customer to Confirm Before Calling
DoExpressCheckoutPayment
With Express Checkout, the customer completes the order and approves the payment on your
website, not on PayPal.
IMPORTANT: You must allow the customer to confirm the payment on your website.
Between the response from SetExpressCheckout and calling
DoExpressCheckoutPayment, you must allow the PayPal user to confirm the order. On
your website, display a button labelled “Place Order” or “Pay” that the customer must click
and that calls DoExpressCheckoutPayment.
Edit Shipping
Figure 5.11, “Example of Edit Shipping Button Treatment,” shows the recommended way to
implement an “Edit Shipping” button with Express Checkout.
Website Payments Pro Integration Guide July 2006 71
Design Choices for Best Buying Experience
Best Buying Experience in Shortcut or Mark Implementations
FIGURE 5.11Example of Edit Shipping Button Treatment
If your customer selected a shipping address from his PayPal account, PayPal recommends
that you create an “Edit Shipping” button or hyperlink to return your customer to PayPal to
change that shipping address information. This button or hyperlink allows the customer to
quickly select a different address already on file with PayPal or to enter a new address. An
“Edit Shipping” button or hyperlink also ensures that PayPal can provide you with the updated
AddressStatus about the new, edited shipping address. For details about AddressStatus,
see “GetExpressCheckoutDetailsResponse” on page 84.
The “Edit Shipping” button or hyperlink follows the same integration instructions as
Integration Point 1 “Step 1b: Integration Point 1” on page 29:
z The customer clicks the “Edit Shipping” button or hyperlink on your order review page.
z You send SetExpressCheckoutRequest to PayPal.
z PayPal returns SetExpressCheckoutResponse.
z You redirect your customer’s browser to PayPal.
NOTE: Your customers are not asked to log in again if they have logged in to PayPal within
the last five minutes.
The following are special considerations about implementing “Edit Shipping” function. For
complete details about SetExpressCheckoutRequest, see “SetExpressCheckoutRequest”
on page 77.
Design Choices for Best Buying Experience
Best Buying Experience in Shortcut or Mark Implementations
72 July 2006 Website Payments Pro Integration Guide
Reapproving PayPal at Integration Point 3
If the customer-selected funding sources are no longer applicable when you call
DoExpressCheckoutPaymentRequest to PayPal, PayPal returns error code 10422. This
error can occur if the final OrderTotal is significantly higher than the original OrderTotal
on SetExpressCheckoutRequest.
If you receive this error message, PayPal recommends that you return your customer to PayPal
to review and approve new, valid funding sources. Although this error is rare, you should
consider trapping the error to display a message to the customer describing what happened,
along with a button or hyperlink to return to PayPal.
Consider displaying an error page like that shown in “Example Message for Reapproving
PayPal” on page 73.
TABLE 5.2 SetExpressCheckoutRequest Usage Notes for “Edit Shipping”
Element
Required
or
Optional? Notes
Token Optional To identify this request as part of the same checkout session, use the
Token value PayPal originally returned in
SetExpressCheckoutResponse after your first invocation of
SetExpressCheckoutRequest.
OrderTotal Required The total estimated cost of the order to the customer.
Because your program should know the shipping and tax charges at
this point, be sure to send an updated OrderTotal that includes those
charges.
MaxAmount Optional The expected maximum total amount of the complete order, including
shipping and tax charges.
You should set MaxAmount at least equal to the updated OrderTotal.
ReturnURL Required URL to which the customer’s browser is returned after approving use
of PayPal.
Set ReturnURL to your order review page or the page on which the
customer clicked the “Edit Shipping” button or hyperlink.
CancelURL Required URL to which the customer is returned if he decides not to use PayPal.
Set CancelURL to your order review page or the page on which the
customer clicked the “Edit Shipping” button or hyperlink. It is likely
that at this point if the customer clicks Cancel on PayPal, the customer
is trying to cancel the editing of the shipping address, not the approval
of the use of PayPal.
Website Payments Pro Integration Guide July 2006 73
Design Choices for Best Buying Experience
Best Buying Experience in Shortcut or Mark Implementations
FIGURE 5.12Example Message for Reapproving PayPal
For the Return to PayPal button or hyperlink, the programming is the same as for Integration
Point 1:
z Your customer clicks the “Return to PayPal” button on your error page.
z You send SetExpressCheckoutRequest to PayPal.
z PayPal returns the SetExpressCheckoutResponse.
z You redirect the customer ‘s browser to PayPal.
NOTE: If this redirection occurs within five minutes of the customer’s last login to PayPal,
the customer is not asked to log in again.
Special considerations for the Return to PayPal function are the same as for “Edit Shipping”
on page 70.
If your customer clicks “Cancel use of PayPal,” redirect the customer’s browser to a page
where he can select a new payment method.
Design Choices for Best Buying Experience
Best Buying Experience in Shortcut or Mark Implementations
74 July 2006 Website Payments Pro Integration Guide
Website Payments Pro Integration Guide July 2006 75
6
Express Checkout API
The Express Checkout API is the Website Payments Pro alternative to standard PayPal
shopping cart processing.
The Express Checkout API consists of three distinct SOAP requests that you make at the three
integration points during a customer checkout:
1.SetExpressCheckout
2.GetExpressCheckoutDetails
3.DoExpressCheckoutPayment
PayPal-supported Currencies
The following currencies are supported by PayPal.
IMPORTANT: All currency amount fields in the three Express Checkout APIs require that
the currencyID attribute be set to one of the supported currency codes. For
any one particular buyer’s checkout session, do not mix currencies either in
any single SOAP request or across SOAP requests. For example, do not set
currencyID to USD in one request and then to GBP in a later request for
the same buyer.
TABLE 6.1 PayPal-supported Currencies and Currency Codes
Code Currency
AUD Australian Dollar
CAD Canadian Dollar
EUR Euro
GBP Pound Sterling
JPY Japanese Yen
USD US Dollar
Express Checkout API
SetExpressCheckout
76 July 2006 Website Payments Pro Integration Guide
Set ExpressCheckout
SetExpressCheckout indicates to PayPal that you are using Express Checkout to obtain
payment from your customer.
Diagram of Set ExpressCheckout Types
The following diagram represents the composition of the
SetExpressCheckoutRequestType and SetExpressCheckoutResponseType
elements. Elements required in the request are indicated with an asterisk.
FIGURE 6.1 SetExpressCheckout Types
Website Payments Pro Integration Guide July 2006 77
Express Checkout API
SetExpressCheckout
SetExpressCheckoutRequest
Request to use PayPal Express Checkout to obtain payment.
IMPORTANT: Any fields in the WSDL or XSD files that are not described here are ignored.
For example, do not set CountryName.
Fields
TABLE 6.2 SetExpressCheckoutRequest Fields
Element Description Data Type
Allowable
Values
Required
?
Token
On your first invocation of
SetExpressCheckoutRequest, the value of
this token is returned by
SetExpressCheckoutResponse.
IMPORTANT: Include this element and its value
only if you want to modify an
existing checkout session with
another invocation of
SetExpressCheckoutReque
st; for example, if you want the
customer to edit his shipping
address on PayPal.
Character length and limitations: 20 single-byte
characters
ebl:Express
CheckoutTokenType
See the description
of “Token” on
page 82.
No
OrderTotal
The total cost of the order to the customer. If
shipping cost and tax charges are known, include
them in OrderTotal; if not, OrderTotal should be the
current sub-total of the order.
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Character length and limitations: Must not exceed
$10,000 USD in any currency. No currency
symbol. Regardless of currency, decimal separator
must be a period (.), and the thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
cc:BasicAmount
Type
See description. Yes
Express Checkout API
SetExpressCheckout
78 July 2006 Website Payments Pro Integration Guide
MaxAmount
The expected maximum total amount of the
complete order, including shipping cost and tax
charges.
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Character length and limitations: Must not exceed
$10,000 USD in any currency. No currency
symbol. Regardless of currency, decimal separator
must be a period (.), and the thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
cc:BasicAmount
Type
See description. No
Order
Description
Description of items the customer is purchasing.
Character length and limitations: 127 single-byte
alphanumeric characters
xs:string
See description. No
Custom
A free-form field for your own use, such as a
tracking number or other value you want PayPal to
return on
GetExpressCheckoutDetailsResponse
and
DoExpressCheckoutPaymentResponse.
Character length and limitations: 256 single-byte
alphanumeric characters
xs:string
See description. No
InvoiceID
Your own unique invoice or tracking number.
PayPal returns this value to you on
DoExpressCheckoutPaymentResponse.
Character length and limitations: 127 single-byte
alphanumeric characters
xs:string
See description. No
ReturnURL
URL to which the customer’s browser is returned
after choosing to pay with PayPal.
NOTE: PayPal recommends that the value of
ReturnURL be the final review page on
which the customer confirms the order and
payment.
Character length and limitations: no limit.
xs:string
See description. Yes
CancelURL
URL to which the customer is returned if he does
not approve the use of PayPal to pay you.
NOTE: PayPal recommends that the value of
CancelURL be the original page on which the
customer chose to pay with PayPal.
Character length and limitations: no limit
xs:string
See description. Yes
TABLE 6.2 SetExpressCheckoutRequest Fields
Element Description Data Type
Allowable
Values
Required
?
Website Payments Pro Integration Guide July 2006 79
Express Checkout API
SetExpressCheckout
Address
Customer’s shipping address.
NOTE: If you include a shipping address and set
the AddressOverride element on the
request, PayPal returns this same address in
GetExpressCheckoutDetailsRes
ponse.
ebl:AddressType
See Table 6.3 on
page 81.
No
ReqConfirm
Shipping
The value 1 indicates that you require that the
customer’s shipping address on file with PayPal be
a confirmed address.
NOTE: Setting this element overrides the setting
you have specified in your Merchant
Account Profile.
Character length and limitations: One single-byte
numeric character.
xs:string 0
1
No
NoShipping
The value 1 indicates that on the PayPal pages, no
shipping address fields should be displayed
whatsoever.
Character length and limitations: Four single-byte
numeric character.
xs:string 0
1
No
Address
Override
The value 1 indicates that the PayPal pages should
display the shipping address set by you in the
Address element on this
SetExpressCheckoutRequest, not the
shipping address on file with PayPal for this
customer.
NOTE: Displaying the PayPal street address on file
does not allow the customer to edit that
address.
Character length and limitations: Four single-byte
numeric character.
xs:string 0
1
No
LocaleCode
Locale of pages displayed by PayPal during Express
Checkout.
Character length and limitations: Five single-byte
alphabetic characters, upper- or lowercase.
xs:string
AU or en_AU
DE or de_DE
FR or fr_FR
GB or en_GB
IT or it_IT
JP or ja_JP
US or en_US
No
TABLE 6.2 SetExpressCheckoutRequest Fields
Element Description Data Type
Allowable
Values
Required
?
Express Checkout API
SetExpressCheckout
80 July 2006 Website Payments Pro Integration Guide
PageStyle
Sets the Custom Payment Page Style for payment
pages associated with this button/link. PageStyle
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.
xs:string
See description. No
cpp-header-
image
A URL for the image you want to appear at the top
left of the payment page. The image has a maximum
size of 750 pixels wide by 90 pixels high. PayPal
recommends that you provide an image that is
stored on a secure (https) server.
Character length and limitations: 127
xs:string
See description. No
cpp-header-
border-color
Sets the border color around the header of the
payment page. The border is a 2-pixel perimeter
around the header space, which is 750 pixels wide
by 90 pixels high.
Character length and limitations: Six character
HTML hexadecimal color code in ASCII
xs:string
See description. No
cpp-header-
back-color
Sets the background color for the header of the
payment page.
Character length and limitation: Six character
HTML hexadecimal color code in ASCII
xs:string
See description. No
cpp-payflow-
color
Sets the background color for the payment page.
Character length and limitation: Six character
HTML hexadecimal color code in ASCII
xs:string
See description. No
TABLE 6.2 SetExpressCheckoutRequest Fields
Element Description Data Type
Allowable
Values
Required
?
Website Payments Pro Integration Guide July 2006 81
Express Checkout API
SetExpressCheckout
NOTE: The AddressType elements are required only if you include the Address element in
the SOAP request.
IMPORTANT: Any fields in the WSDL or XSD files that are not described here are ignored.
For example, do not set CountryName.
PaymentAction
How you want to obtain payment:
z Authorization indicates that this payment is a
basic authorization subject to settlement with
PayPal Authorization & Capture.
z Order indicates that this payment is is an order
authorization subject to settlement with PayPal
Authorization & Capture.
z Sale indicates that this is a final sale for which
you are requesting payment.
IMPORTANT: You cannot set PaymentAction to
Sale on
SetExpressCheckoutReque
st and then change PaymentAction
to Authorization on the final API
DoExpressCheckoutPaymen
tRequest.
Character length and limit: Up to 13 single-byte
alphabetic characters
ebl:PaymentAction
CodeType
xs:token
Default: The
transaction
resulting from
DoExpress
Checkout
Payment
Request will be a
final sale.
Authorization
Order
Sale
No
BuyerEmail
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
ebl:EmailAddress
Type
See description. No
TABLE 6.3 Address (Shipping Address): AddressType Elements
Element Descriptions Data Type
Allowable
Values Required?
Name
Person’s name associated with this shipping
address.
Character length and limitations: 32 single-byte
characters
xs:string
See description. No
TABLE 6.2 SetExpressCheckoutRequest Fields
Element Description Data Type
Allowable
Values
Required
?
Express Checkout API
SetExpressCheckout
82 July 2006 Website Payments Pro Integration Guide
SetExpressCheckoutResponse
Response to SetExpressCheckoutRequest.
Fields
Street1
First street address.
Character length and limitations: 100 single-byte
characters
xs:string
See description. Yes
Street2
Second street address.
Character length and limitations: 100 single-byte
characters
xs:string
See description. No
CityName
Name of city.
Character length and limitations: 40 single-byte
characters
xs:string
See description. Yes
StateOr
Province
State or province
Character length and limitations: 40 single-byte
characters
xs:string
See description. Yes
PostalCode
U.S. Zip code or other country-specific postal code
Character length and limitations: 20 single-byte
characters
xs:string
See description. Yes
Country
Country code.
Character limit: Two single-byte characters.
ebl:CountryCode
Type
xs:string
See Appendix B. Yes
TABLE 6.4 SetExpressCheckoutResponse Fields
Element Description Data Type Value
Token A timestamped token by which you identify to
PayPal that you are processing this payment with
Express Checkout.
NOTE: The token expires after three hours.
If you set Token in the
SetExpressCheckoutRequest, the value of
Token in the response is identical to the value in
the request.
Character length and limitations: 20 single-byte
characters
xs:string
See description.
TABLE 6.3 Address (Shipping Address): AddressType Elements
Element Descriptions Data Type
Allowable
Values Required?
Website Payments Pro Integration Guide July 2006 83
Express Checkout API
GetExpressCheckoutDetails
Get ExpressCheckout Detai l s
GetExpressCheckoutDetails returns information about the customer, including name
and address on file with PayPal.
Diagram of GetExpressCheckoutDetails Types
The following diagram represents the composition of the
GetExpressCheckoutDetailsRequestType and
GetExpressCheckoutDetailsResponseType elements.
Elements required in the request are indicated with an asterisk.
FIGURE 6.2 GetExpressCheckout Types
Express Checkout API
GetExpressCheckoutDetails
84 July 2006 Website Payments Pro Integration Guide
GetExpressCheckoutDetailsRequest
Obtain details about a payment to be processed by PayPal Express Checkout.
Fields
GetExpressCheckoutDetailsResponse
Response to GetExpressCheckoutDetailsRequest.
Fields
TABLE 6.5 GetExpressCheckoutDetailsRequest Fields
Element Description Data Type
Allowable
Values
Required
?
Token A timestamped token, the value of which was
returned by
SetExpressCheckoutResponse.
Character length and limitations: 20 single-byte
characters
xs:string
An unexpired token Yes
TABLE 6.6 GetExpressCheckoutDetailsResponse Fields
Element Description Data Type Possible Values
Token
The timestamped token value that was returned by
SetExpressCheckoutResponse and passed
on
GetExpressCheckoutDetailsRequest.
Character length and limitations: 20 single-byte
characters
xs:string
See the description
of “Token” on
page 82.
PayerInfo
Information about the payer. ebl:PayerInfoType See Table 6.7 on
page 85.
Custom
A free-form field for your own use, as set by you in
the Custom element of
SetExpressCheckoutRequest.
Character length and limitations: 256 single-byte
alphanumeric characters
xs:string
See description.
InvoiceID
Your own invoice or tracking number, as set by you
in the InvoiceID element of
SetExpressCheckoutRequest.
Character length and limitations: 127 single-byte
alphanumeric characters
xs:string
See description.
Website Payments Pro Integration Guide July 2006 85
Express Checkout API
GetExpressCheckoutDetails
NOTE: Empty elements are returned if there is no representative data for the customer. For
example, if the customer does not represent a business (and therefore has no business
name on file with PayPal), the returned element has no value, like this:
<PayerBusiness/>.
NOTE:
.
ContactPhone
Payer’s contact telephone number.
NOTE: PayPal returns a contact telephone number
only if your Merchant account profile
settings require that the buyer enter one.
Character length and limitations: Field mask is
XXX-XXX-XXXX (for US numbers) or +XXX
XXXXXXXX (for international numbers)
xs:string
See description.
TABLE 6.7 Response: PayerInfoType Elements
Element Description DataType Possible Values
Payer Email address of payer.
Character length and limitations: 127 single-byte
characters
ebl:EmailAddress
Type
See description.
PayerID Unique PayPal customer account number.
Character length and limitations:17 single-byte
characters maximum.
ebl:UserIDType See description.
PayerStatus Status of payer.
Character length and limitations: 10 single-byte
alphabetic characters.
ebl:PayPalUser
StatusCodeType
verified
unverified
PayerName First and last name of payer
ebl:PersonNameType
See Table 6.8 on
page 86.
PayerCountry Payer’s country of residence in the form of ISO
standard 3166 two-character country codes.
Character length and limitations: Two single-byte
characters
ebl:CountryCode
Type
See Appendix B.
PayerBusiness Payer’s business name.
Character length and limitations: 127 single-byte
characters
xs:string
See description.
Address
Payer's shipping address address information.
xs:string
See Table 6.9 on
page 86.
TABLE 6.6 GetExpressCheckoutDetailsResponse Fields
Element Description Data Type Possible Values
Express Checkout API
GetExpressCheckoutDetails
86 July 2006 Website Payments Pro Integration Guide
TABLE 6.8 Response: PayerName Elements
Element Description DataType Possible Values
Salutation
Payer’s salutation
Character length and limitations: 20 single-byte
characters
xs:string See description.
FirstName
Payer’s first name
Character length and limitations: 25 single-byte
characters
ebl:PersonNameType See description.
MiddleName
Payer’s middle name
Character length and limitations: 25 single-byte
characters
ebl:NameType
LastName
Payer’s last name
Character length and limitations: 25 single-byte
characters
ebl:NameType See description.
Suffix
Payer’s suffix
Character length and limitations: 12 single-byte
characters
ebl:SuffixType
See description.
FirstName
Payer’s first name.
Character length and limitations: 25 single-byte
characters
ebl:NameType See description.
LastName
Payer’s last name.
Character length and limitations: 25 single-byte
characters
ebl:NameType See description.
TABLE 6.9 Response: AddressType Fields
Element Descriptions Data Type Possible Values
AddressStatus
Status of street address on file with PayPal ebl:AddressStatus
TypeCode
none
Confirmed
Unconfirmed
Name
Person’s name associated with this address.
Character length and limitations: 32 single-byte
characters
xs:string
See description.
Street1
First street address.
Character length and limitations: 100 single-byte
characters
xs:string
See description.
Website Payments Pro Integration Guide July 2006 87
Express Checkout API
DoExpressCheckoutPayment
DoExpressCheckoutPayment
With DoExpressCheckoutPayment, you either obtain payment through Express Checkout for a
final sale or request authorization for later capture of payment.
Diagram of DoExpressCheckoutPayment Types
The following diagram represents the composition of the
DoExpressCheckoutPaymentRequestType and
DoExpressCheckoutPaymentResponseType elements. Elements required in the request
are indicated with an asterisk.
Street2
Second street address.
Character length and limitations: 100 single-byte
characters
xs:string
See description.
CityName
Name of city.
Character length and limitations: 40 single-byte
characters
xs:string
See description.
StateOr
Province
State or province
Character length and limitations: 40 single-byte
characters
xs:string
See description.
PostalCode
U.S. Zip code or other country-specific postal code
Character length and limitations: 20 single-byte
characters
xs:string
See description.
Country
Country code.
Character limit: Two single-byte characters.
ebl:CountryCode
Type
xs:string
See Appendix B.
TABLE 6.9 Response: AddressType Fields
Element Descriptions Data Type Possible Values
Express Checkout API
DoExpressCheckoutPayment
88 July 2006 Website Payments Pro Integration Guide
FIGURE 6.3 DoExpressCheckoutPayment Types
Website Payments Pro Integration Guide July 2006 89
Express Checkout API
DoExpressCheckoutPayment
DoExpressCheckoutPaymentRequest
Request to obtain payment with PayPal Express Checkout.
IMPORTANT: PayPal requires that a merchant using Express Checkout display to the
customer the same exact amount that the merchant sends to PayPal in the
OrderTotal element with the DoExpressCheckoutPaymentRequest
API.
Fields
TABLE 6.10 DoExpressCheckoutPaymentRequest Fields
Element Description Data Type
Allowable
Values
Required
?
Token
The timestamped token value that was returned by
SetExpressCheckoutResponse and passed
on
GetExpressCheckoutDetailsRequest.
Character length and limitations: 20 single-byte
characters
xs:string
See description. Yes
PaymentAction
How you want to obtain payment:
z Authorization indicates that this payment is a
basic authorization subject to settlement with
PayPal Authorization & Capture.
z Order indicates that this payment is is an order
authorization subject to settlement with PayPal
Authorization & Capture.
z Sale indicates that this is a final sale for which
you are requesting payment.
IMPORTANT: You cannot set PaymentAction to
Sale on
SetExpressCheckoutReque
st and then change PaymentAction
to Authorization on the final PayPal
Express Checkout API
DoExpressCheckoutPaymen
tRequest.
Character length and limit: Up to 13 single-byte
alphabetic characters
ebl:PaymentAction
CodeType
xs:token
Default: The
transaction
resulting from
DoExpress
Checkout
Payment
Request will be a
final sale.
Authorization
Order
Sale
No
PayerID
Encrypted PayPal customer account identification
number as returned by
GetExpressCheckoutDetailsResponse.
Character length and limitations: 127 single-byte
characters.
ebl:UserIDType
See description. Yes
Express Checkout API
DoExpressCheckoutPayment
90 July 2006 Website Payments Pro Integration Guide
PaymentDetails
Information about the payment ebl:PaymentDetails
Type
See Table 6.11 on
page 90.
Yes
TABLE 6.11 Request: PaymentDetailsType Fields
Element Description Data Type
Allowable
Values
Required
?
OrderTotal Total of order, including shipping, handling, and
tax.
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Character length and limitations: Must not exceed
$10,000 USD in any currency. No currency
symbol. Regardless of currency, decimal separator
must be a period (.), and the thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
ebl:BasicAmount
Type
See description. Yes
ItemTotal Sum of cost of all items in this order.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
ebl:BasicAmount
Type
See description. No
Shipping
Total
Total shipping costs for this order.
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Character length and limitations: Must not exceed
$10,000 USD in any currency. No currency
symbol. Regardless of currency, decimal separator
must be a period (.), and the thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
ebl:BasicAmount
Type
See description. No
TABLE 6.10 DoExpressCheckoutPaymentRequest Fields
Element Description Data Type
Allowable
Values
Required
?
Website Payments Pro Integration Guide July 2006 91
Express Checkout API
DoExpressCheckoutPayment
Handling
Total
Total handling costs for this order.
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Character length and limitations: Must not exceed
$10,000 USD in any currency. No currency
symbol. Regardless of currency, decimal separator
must be a period (.), and the thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
ebl:BasicAmount
Type
See description. No
TaxTotal
Sum of tax for all items in this order.
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Character length and limitations: Must not exceed
$10,000 USD in any currency. No currency
symbol. Regardless of currency, decimal separator
must be a period (.), and the thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
ebl:BasicAmount
Type
See description. No
Order
Description
Description of items the customer is purchasing.
Character length and limitations: 127 single-byte
alphanumeric characters
xs:string
See description. No
Custom
A free-form field for your own use.
Character length and limitations: 256 single-byte
alphanumeric characters
xs:string
See description. No
InvoiceID
Your own invoice or tracking number.
Character length and limitations: 127 single-byte
alphanumeric characters
xs:string
See description. No
ButtonSource
An identification code for use by third-party
applications to identify transactions.
Character length and limitations: 32 single-byte
alphanumeric characters
xs:string
See description. No
NotifyURL
Your URL for receiving Instant Payment
Notification (IPN) about this transaction.
NOTE: If you do not specify NotifyURL in the
request, the notification URL from your
Merchant Profile is used, if one exists.
Character length and limitations: 2,048 single-byte
alphanumeric characters
xs:string
See description. No
TABLE 6.11 Request: PaymentDetailsType Fields
Element Description Data Type
Allowable
Values
Required
?
Express Checkout API
DoExpressCheckoutPayment
92 July 2006 Website Payments Pro Integration Guide
NOTE: The AddressType elements are required only if you include the Address element in
the SOAP request.
IMPORTANT: Any fields in the WSDL or XSD files that are not described here are ignored.
For example, do not set CountryName.
ShipToAddress
Address the order will be shipped to. ebl:AddressType See Table 6.12 on
page 92.
No
PaymentDetails
Item
Details about each individual item included in the
order
ebl:PaymentDetails
ItemType
See Table 6.13 on
page 93.
No
TABLE 6.12 Request: ShipToAddress: AddressType Fields
Element Descriptions Data Type
Allowable
Values
Required
?
Name
Person’s name associated with this address.
Character length and limitations: 32 single-byte
characters
xs:string
See description. Yes
Street1
First street address.
Character length and limitations: 100 single-byte
characters
xs:string
See description. Yes
Street2
Second street address.
Character length and limitations: 100 single-byte
characters
xs:string
See description. No
CityName
Name of city.
Character length and limitations: 40 single-byte
characters
xs:string
See description. Yes
StateOr
Province
State or province.
Character length and limitations: 40 single-byte
characters
xs:string
See description. No
PostalCode
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte
characters
xs:string
See description. No
Country
Country code.
Character limit: Two single-byte characters
ebl:CountryCode
Type
xs:string
See Appendix B. Yes
TABLE 6.11 Request: PaymentDetailsType Fields
Element Description Data Type
Allowable
Values
Required
?
Website Payments Pro Integration Guide July 2006 93
Express Checkout API
DoExpressCheckoutPayment
DoExpressCheckoutPaymentResponse
Response to DoExpressCheckoutPaymentRequest.
TABLE 6.13 Request: PaymentDetailsItemType Fields
Element Description Data Type
Allowable
Values
Required
?
Name
Item name.
Character length and limitations: 127 single-byte
characters
xs:string
See description. No
Amount
Cost of item
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Character length and limitations: Must not exceed
$10,000 USD in any currency. No currency
symbol. Regardless of currency, decimal separator
must be a period (.), and the thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
ebl:BasicAmount
Type
See description. No
Number
Item number.
Character length and limitations: 127 single-byte
characters
xs:string
See description. No
Quantity
Item quantity.
Character length and limitations: Any positive
integer
xs:string
See description. No
Tax
Item sales tax.
Currency code must be set the same as for
OrderTotal.
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Character length and limitations: Must not exceed
$10,000 USD in any currency. No currency
symbol. Regardless of currency, decimal separator
must be a period (.), and the thousands separator
must be a comma (,). Equivalent to nine characters
maximum for USD.
ebl:BasicAmount
Type
See description. No
Express Checkout API
DoExpressCheckoutPayment
94 July 2006 Website Payments Pro Integration Guide
Fields
TABLE 6.14 DoExpressCheckoutPaymentResponse Fields
Element Description Data Type Possible Values
Token
The timestamped token value that was returned by
SetExpressCheckoutResponse and passed
on
GetExpressCheckoutDetailsRequest.
Character length and limitations:20 single-byte
characters
xs:string
See the description
of “Token” on
page 82.
PaymentInfo
Information about the payment. ebl:PaymentInfo
Type
See Table 6.15 on
page 94.
TABLE 6.15 Response: PaymentInfoType Elements
Element Description Data Type Possible Values
TransactionID Unique transaction ID of the payment.
IMPORTANT: If the PaymentAction of the request
was Authorization or Order, the
value of TransactionID is your
AuthorizationID for use with the
Authorization & Capture APIs.
Character length and limitations:19 single-byte
characters
xs:string
Transaction-
specific
Transaction
Type
The type of transaction
Character length and limitations:15 single-byte
characters
ns:Payment
TransactionCode
Type
cart
express-checkout
PaymentType Indicates whether the payment is instant or delayed.
Character length and limitations: Seven single-byte
characters
ebl:PaymentCode
Type
xs:string
none
echeck
instant
PaymentDate Time/date stamp of payment
xs:dateTime
Transaction-
specific
GrossAmount The final amount charged, including any shipping
and taxes from your Merchant Profile.
Character length and limitations: Does not exceed
$10,000 USD in any currency. No currency symbol.
Regardless of currency, decimal separator is a
period (.), and the thousands separator is a comma
(,). Equivalent to nine characters maximum for
USD.
ebl:BasicAmount
Type
Transaction-
specific
Website Payments Pro Integration Guide July 2006 95
Express Checkout API
DoExpressCheckoutPayment
FeeAmount 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
thousands separator is a comma (,). Equivalent
to nine characters maximum for USD.
ebl:BasicAmount
Type
Transaction-
specific
SettleAmount Amount deposited in your PayPal account after a
currency conversion.
ebl:BasicAmount
Type
Transaction-
specific
TaxAmount 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
thousands separator is a comma (,). Equivalent
to nine characters maximum for USD.
ebl:BasicAmount
Type
xs:string
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 customer’s
account.
Character length and limitations: a decimal that
does not exceed 17 characters, including decimal
point
xs:string
Transaction-
specific
PaymentStatus Status of the payment:
Completed: The payment has been completed, and
the funds have been added successfully to your
account balance.
Pending: The payment is pending. See the
PendingReason element for more information.
ebl:PaymentStatus
CodeType
xs:token
Completed
Pending
TABLE 6.15 Response: PaymentInfoType Elements
Element Description Data Type Possible Values
Express Checkout API
DoExpressCheckoutPayment
96 July 2006 Website Payments Pro Integration Guide
PendingReason 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.
ebl:PendingStatus
CodeType
xs:token
none
address
echeck
intl
multi-currency
verify
other
TABLE 6.15 Response: PaymentInfoType Elements
Element Description Data Type Possible Values
Website Payments Pro Integration Guide July 2006 97
7
Direct Payment API
With the Direct Payment API, you can obtain payment through PayPal directly from a buyer’s
credit card without the buyer logging into PayPal.
Diagram of DoDirectPayment Types
The following diagram represents the composition of the DoDirectPaymentRequestType
and DoDirectPaymentResponseType elements. Elements required in the request are
indicated with an asterisk.
FIGURE 7.1 DoDirectPayment Types
Direct Payment API
DoDirectPaymentRequest
98 July 2006 Website Payments Pro Integration Guide
DoDi rect Payment Request
Request to use PayPal Direct Payment to obtain payment.
You must include the PaymentAction element in DoDirectPaymentRequest. Allowable
values for the PaymentAction element are Sale or Authorization:
z Set PaymentAction to Sale if the buyer’s order is final (for example, if the total cost of
the order is complete with shipping, handling and tax charges). This transaction is your
payment, and you expect no additional charge to the buyer.
z Set PaymentAction to Authorization if the total cost of the order at point of sale is
not complete for some reason (such as unknown shipping charges) and you expect to
capture funds after checkout is complete. You can then use PayPal Authorization &
Capture to obtain payment.
In either case, besides the PaymentAction element, DoDirectPaymentRequest requires
additional elements, such as the amount of the transaction, IP address of the buyer’s browser,
credit card number, type, and expiration date, and information about both the payer and the
payment.
Fields
TABLE 7.1 DoDirectPaymentRequest Fields
Element Description Data Type
Allowable
Values
Required
?
PaymentAction How you want to obtain payment:
z Authorization indicates that this payment is a
basic authorization subject to settlement with
PayPal Authorization & Capture.
z Sale indicates that this is a final sale for which
you are requesting payment.
Character length and limit: Up to 13 single-byte
alphabetic characters
ebl:PaymentAction
CodeType
xs:token
Default: The
transaction
resulting from
DoDirect
Payment
Request will be a
final sale.
Authorization
Sale
NOTE: Order is
not allowed
for Direct
Payment.
No
CreditCard Information about the credit card to be charged.
ebl:CreditCard
DetailsType
See Table 7.2 on
page 99.
Yes
PaymentDetails Information about the payment
ebl:PaymentDetails
Type
See Table 7.3 on
page 100.
Yes
Website Payments Pro Integration Guide July 2006 99
Direct Payment API
DoDirectPaymentRequest
IPAddress IP address of the payer’s browser as recorded in its
HTTP request to your website.
NOTE: PayPal records this IP addresses as a means
to detect possible fraud.
Character length and limitations: 15 single-byte
characters, including periods, in dotted-quad
format: ???.???.???.???
xs:string
Any valid Internet
Protocol address.
Yes
Merchant
SessionId
Your customer session identification token.
NOTE: PayPal records this optional session
identification token as an additional means
to detect possible fraud.
Character length and limitations: 64 single-byte
numeric characters
xs:string
No
TABLE 7.2 CreditCardDetailsType Fields
Element Description Data Type
Allowable
Values
Required
?
CreditCardType Type of credit card.
Character length and limitations: Up to ten single-
byte alphabetic characters.
IMPORTANT: If the credit card type is Switch or
Solo:
1. The value of PaymentAction must be
Authorization.
2. The currencyId must be GBP.
ebl:CreditCardType
Type
Visa
MasterCard
Discover
Amex
Switch. See
important note in
description.
Solo. See
important note in
description.
Yes
CreditCard
Number
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.
xs:string
See description. Yes
ExpMonth Credit card expiration month
Character length and limitations: Two single-byte
numeric characters, including leading zero.
xs:int
See description. Yes
ExpYear Credit card expiration year
Character length and limitations: Four single-byte
numeric characters.
xs:int
See description. Yes
TABLE 7.1 DoDirectPaymentRequest Fields
Element Description Data Type
Allowable
Values
Required
?
Direct Payment API
DoDirectPaymentRequest
100 July 2006 Website Payments Pro Integration Guide
CVV2 Card Verification Value, version 2.
NOTE: You must include a CVV2 value for those
credit cards that use CVV2.
Required for Visa, MasterCard, American Express,
and Discover cards. Other card types might not
require a CVV2 value.
Character length for Visa, MasterCard, and
Discover: exactly three digits.
Character length for American Express: exactly
four digits.
IMPORTANT: To comply with credit card process-
ing regulations, once a transaction
has been completed, you must not
store the value of CVV2.
xs:string
See description. No.
See note in
description.
CardOwner Details about the owner of the credit card.
ns:PayerInfoType
See Table 7.7 on
page 106.
Yes
StartMonth Month that Switch or Solo card was issued.
Character length: two-digit, zero-filled if necessary.
xs:int See description. No.
StartYear Year that Switch or Solo card was issued.
Character length: four digits.
xs:int See description. No.
IssueNumber Issue number of Switch or Solo card.
Character length: two numeric digits maximum.
xs:int See description. No.
TABLE 7.3 Request: PaymentDetailsType Fields
Element Description Data Type Allowable Values Required?
OrderTotal
Total of order, including shipping, handling, and
tax.
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
ebl:BasicAmount
Type
See description. Yes
ItemTotal
Sum of cost of all items in this order.
Character length and limitations: 127 single-byte
characters
ebl:BasicAmount
Type
See description. No
TABLE 7.2 CreditCardDetailsType Fields
Element Description Data Type
Allowable
Values
Required
?
Website Payments Pro Integration Guide July 2006 101
Direct Payment API
DoDirectPaymentRequest
ShippingTotal
Total shipping costs for this order.
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
ebl:BasicAmount
Type
See description. No
HandlingTotal
Total handling costs for this order.
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
ebl:BasicAmount
Type
See description. No
TaxTotal
Sum of tax for all items in this order.
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
ebl:BasicAmount
Type
See description. No
Order
Description
Description of items the customer is purchasing.
Character length and limitations: 127 single-byte
alphanumeric characters
xs:string
See description. No
Custom A free-form field for your own use.
Character length and limitations: 256 single-byte
alphanumeric characters
xs:string
See description. No
InvoiceID Your own invoice or tracking number, as set by you
in the InvoiceID element of
SetExpressCheckoutRequest.
Character length and limitations: 127 single-byte
alphanumeric characters
xs:string
See description. No
ButtonSource An identification code for use by third-party
applications to identify transactions.
Character length and limitations: 32 single-byte
alphanumeric characters
xs:string
See description. No
TABLE 7.3 Request: PaymentDetailsType Fields
Element Description Data Type Allowable Values Required?
Direct Payment API
DoDirectPaymentRequest
102 July 2006 Website Payments Pro Integration Guide
IMPORTANT: Any fields in the WSDL or XSD files that are not described here are ignored.
For example, do not set CountryName.
NotifyURL Your URL for receiving Instant Payment
Notification (IPN) about this transaction.
NOTE: If you do not specify NotifyURL in the
request, the notification URL from your
Merchant Profile is used, if one exists.
Character length and limitations: 2,048 single-byte
alphanumeric characters
xs:string
See description. No
ShipToAddress Address the order will be shipped to. ebl:AddressType See Table 7.4 on
page 102.
No
PaymentDetails
Item
Details about each individual item included in the
order
ebl:PaymentDetails
ItemType
See Table 7.6 on
page 106.
No
TABLE 7.4 Request: ShipToAddress: AddressType Fields
Element Descriptions Data Type
Allowable
Values
Required
?
Name
Person’s name associated with this address.
Character length and limitations: 32 single-byte
characters
xs:string
See description. Yes
Street1
First street address.
Character length and limitations: 100 single-byte
characters
xs:string
See description. Yes
Street2
Second street address.
Character length and limitations: 100 single-byte
characters
xs:string
See description. No
CityName
Name of city.
Character length and limitations: 40 single-byte
characters
xs:string
See description. Yes
StateOr
Province
State or province.
Character length and limitations: 40 single-byte
characters
xs:string
See Table 7.5 on
page 103
No
PostalCode
U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte
characters
xs:string
See description. No
TABLE 7.3 Request: PaymentDetailsType Fields
Element Description Data Type Allowable Values Required?
Website Payments Pro Integration Guide July 2006 103
Direct Payment API
DoDirectPaymentRequest
Country
Country code.
Character limit: Two single-byte characters
ebl:CountryCode
Type
xs:string
See Appendix B. Yes
TABLE 7.5 StateOrProvince: Abbreviations for Canada and U.S.
Canadian Province or U.S. State
Alberta AB
British Columbia BC
Manitoba MB
New Brunswick NB
Newfoundland and Labrador NF
Northwest_Territories NT
Nova_Scotia NS
Nunavut NU
Ontario ON
Prince_Edward_Island PE
Quebec QC
Saskatchewan SK
Yukon YK
Alabama AL
Alaska AK
American_Samoa AS
Arizona AZ
Arkansas AR
California CA
Colorado CO
Connecticut CT
Delaware DE
TABLE 7.4 Request: ShipToAddress: AddressType Fields
Element Descriptions Data Type
Allowable
Values
Required
?
Direct Payment API
DoDirectPaymentRequest
104 July 2006 Website Payments Pro Integration Guide
District Of Columbia DC
Federated States Of Micronesia FM
Florida FL
Georgia GA
Guam GU
Hawaii HI
Idaho ID
Illinois IL
Indiana IN
Iowa IA
Kansas KS
Kentucky KY
Louisiana LA
Maine ME
Marshall_Islands MH
Maryland MD
Massachusetts MA
Michigan MI
Minnesota MN
Mississippi MS
Missouri MO
Montana MT
Nebraska NE
Nevada NV
New Hampshire NH
New Jersey NJ
New Mexico NM
New York NY
TABLE 7.5 StateOrProvince: Abbreviations for Canada and U.S.
Canadian Province or U.S. State
Website Payments Pro Integration Guide July 2006 105
Direct Payment API
DoDirectPaymentRequest
North Carolina NC
North Dakota ND
Northern Mariana Islands MP
Ohio OH
Oklahoma OK
Oregon OR
Palau PW
Pennsylvania PA
Puerto Rico PR
Rhode Island RI
South Carolina SC
South Dakota SD
Tennessee TN
Texas TX
Utah UT
Vermont VT
Virgin_Islands VI
Virginia VA
Washington WA
West_Virginia WV
Wisconsin WI
Wyoming WY
Armed_Forces_Americas AA
Armed_Forces AE
Armed_Forces_Pacific AP
TABLE 7.5 StateOrProvince: Abbreviations for Canada and U.S.
Canadian Province or U.S. State
Direct Payment API
DoDirectPaymentRequest
106 July 2006 Website Payments Pro Integration Guide
TABLE 7.6 Request: PaymentDetailsItemType Fields
Element Description Data Type
Allowable
Values
Required
?
Name
Item name.
Character length and limitations: 127 single-byte
characters
xs:string
See description. No
Amount
Cost of item
NOTE: You must set the currencyID attribute to
one of the three-character currency codes
for any of the supported PayPal currencies.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
ebl:BasicAmount
Type
See description. No
Number
Item number.
Character length and limitations: 127 single-byte
characters
xs:string
See description. No
Quantity
Item quantity.
Character length and limitations: Any positive
integer
xs:string
See description. No
Tax
Item sales tax.
Character length and limitations: any valid currency
amount; currency code is set the same as for
OrderTotal.
ebl:BasicAmount
Type
See description. No
TABLE 7.7 CardOwner: PayerInfoType Fields
Element Description DataType
Allowable
Values
Required
?
Payer Email address of payer.
Character length and limitations: 127 single-byte
characters
ns:EmailAddress
Type
See description. No
FirstName Payer’s first name.
Character length and limitations: 25 single-byte
characters
ns:PersonName
Type
See description. Yes
LastName Payer’s last name.
Character length and limitations: 25 single-byte
characters
ns:PersonName
Type
See description. Yes
Website Payments Pro Integration Guide July 2006 107
Direct Payment API
DoDirectPaymentRequest
Address Payer’s billing address information
ns:AddressType
See Table 7.8 on
page 107.
Yes
TABLE 7.8 CardOwner: AddressType Fields
Element Description DataType
Allowable
Values
Required
?
Street1
First street address
Character length and limitations: 100 single-byte
characters
xs:string
See description. Yes
Street2
Second street address
Character length and limitations: 100 single-byte
characters
xs:string
See description. No
CityName
Name of city
Character length and limitations: 40 single-byte
characters
xs:string
See description. Yes
StateOr
Province
State or province
Character length and limitations: 40 single-byte
characters
xs:string
See description. Yes
Country
Country code.
Character length and limitations: Two single-byte
characters.
ebl:CountryCode
Type
xs:string
See Appendix 1. Yes
PostalCode
U.S. Zip code or other country-specific postal code
Character length and limitations: 20 single-byte
characters
xs:string
See description. Yes
TABLE 7.7 CardOwner: PayerInfoType Fields
Element Description DataType
Allowable
Values
Required
?
Direct Payment API
DoDirectPaymentResponse
108 July 2006 Website Payments Pro Integration Guide
DoDi rect Payment Response
Response to DoDirectPaymentRequest.
The Direct Payment API response contains the TransactionID element. In the case of a
final Sale, TransactionID is your record of the transaction processed with PayPal. In the
case of an Authorization, TransactionID is your key to capturing funds with PayPal
Authorization & Capture.
DoDirectPaymentResponse also returns the result of checking the buyer’s postal address
and credit card number (as submitted by you with DoDirectPaymentRequest) against the
U.S. banking industry standard Address Verification System (AVS) and Credit Card
Verification (CVV2) system.
Fields
TABLE 7.9 DoDirectPaymentResponse Fields
Element Description Data Type Possible Values
TransactionID Unique transaction ID of the payment.
IMPORTANT: If the PaymentAction of the request
was Authorization, the value of
TransactionID is your
AuthorizationID for use with the
Authorization & Capture APIs.
Character length and limitations: 19 single-byte
characters
xs:string
See description.
Amount
The amount of the payment as specified by you on
DoDirectPaymentRequest.
ebl:BasicAmount
Type
See description.
AVSCode Address Verification System response code.
Character limit: One single-byte alphanumeric
character
xs:string
See Table 7.10,
“AVS Response
Codes” on
page 109.
CVV2Code Result of the CVV2 check by PayPal.
xs:string
See Table 7.11,
“CVV2 Response
Codes” on
page 109.
Website Payments Pro Integration Guide July 2006 109
Direct Payment API
DoDirectPaymentResponse
TABLE 7.10 AVS Response Codes
AVS
Code Meaning Matched Details
A Address Address only (no ZIP)
B International “A” Address only (no ZIP)
C International “N” None
D International “X” Address and Postal Code
E Not allowed for MOTO (Internet/Phone)
transactions
Not applicable
F UK-specific “X” Address and Postal Code
G Global Unavailable Not applicable
I International Unavailable Not applicable
N No None
P Postal (International “Z”) Postal Code only (no Address)
R Retry Not applicable
S Service not Supported Not applicable
U Unavailable Not applicable
W Whole ZIP Nine-digit ZIP code (no Address)
X Exact match Address and nine-digit ZIP code
Y Yes Address and five-digit ZIP
Z ZIP Five-digit ZIP code (no Address)
All
others
Error Not applicable
TABLE 7.11 CVV2 Response Codes
CVV2
Code Meaning Matched Details
M Match CVV2
N No match None
Direct Payment API
DoDirectPaymentResponse
110 July 2006 Website Payments Pro Integration Guide
P Not Processed Not applicable
S Service not Supported Not applicable
U Unavailable Not applicable
X No response Not applicable
All
others
Error Not applicable
TABLE 7.11 CVV2 Response Codes
CVV2
Code Meaning Matched Details
Website Payments Pro Integration Guide June 2006 111
8
Authorization & Capture API
The Authorization & Capture API consists of individual requests and responses, as shown
below.
Funds Availability
Both DoAuthorization and DoReauthorization check the availability of a PayPal member’s
funds to obtain another honor period or to make a payment higher than you originally
authorized, up to 115% of the originally authorized amount (not to exceed an increase of $75
USD).
TABLE 8.1 Authorization & Capture API Names, Purposes, and Types of Authorization
API Purpose
Used With Type
of Authorization
1. DoCapture Settle an order or previously authorized transaction
and obtain payment for either the complete amount
or any portion of it.
Order and Basic
2. DoAuthorization Authorize an order that can be fulfilled over 29
days.
Order only
3. DoVoid Void an original authorization or order Order and Basic
4. DoReauthorization Reauthorize a previously authorized transaction Basic only
Authorization & Capture API
DoCapture
112 June 2006 Website Payments Pro Integration Guide
DoCapt ure
DoCaptureRequest is your request to completely or partially settle an order, an
authorization, or reauthorization.
NOTE: DoCaptureRequest is for use with both basic and order authorizations.
Diagram of DoCapture Types
The following diagram represents the composition of the DoCaptureRequestType and
DoCaptureResponseType elements. Elements required in the request are marked with an
asterisk.
FIGURE 8.1 DoCapture Types
Website Payments Pro Integration Guide June 2006 113
Authorization & Capture API
DoCapture
DoCaptureRequest
Request to capture funds from a PayPal member’s account.
Fields
TABLE 8.2 DoCaptureRequest Fields
Element Description Data Type Allowable Values Required?
Authorization
ID
The authorization identification number of the
payment you want to capture. This can be an order
number, an order authorization number, or a
rauthorization number.
Character length and limits: 19 single-byte
characters maximum
xs:string
See description. Yes
Amount
Amount to capture.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
ebl:BasicAmount
Type
See description. Yes
CompleteType
Indicates if this capture is the last capture you intend
to make. The default is Complete.
NOTE: If CompleteType is Complete, any remaining
amount of the original reauthorized
transaction is automatically voided.
Character length and limits: 12 single-byte
alphanumeric characters
ebl:Complete
CodeType
Default:
Complete
NotComplete
Yes
InvoiceID
Your invoice number or other identification
number.
NOTE: The InvoiceID 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
xs:string See description. No
Note
An informational note about this settlement that is
displayed to the payer in email and in his transaction
history.
Character length and limits: 255 single-byte
characters
xs:string
See description. No
Authorization & Capture API
DoCapture
114 June 2006 Website Payments Pro Integration Guide
DoCaptureResponse
Response to DoCaptureRequest.
Fields
TABLE 8.3 DoCaptureResponse Fields
Element Description Data Type Possible Values
Authorization
ID
The authorization identification number you
specified in the request.
Character length and limits: 19 single-byte
characters maximum
xs:string
See description.
PaymentInfo
Information about the payment. ebl:PaymentInfo
Type
See Table 8.4 on
page 114.
TABLE 8.4 Response: PaymentInfoType Elements
Element Description Data Type Possible Values
TransactionID Unique transaction ID of the payment.
Character length and limitations: 17 single-byte
characters
xs:string
Transaction-
specific
Transaction
Type
The type of transaction
Character length and limitations: 15 single-byte
characters
ns:Payment
TransactionCode
Type
cart
express-checkout
PaymentType Indicates whether the payment is instant or delayed.
Character length and limitations: Seven single-byte
characters
ebl:PaymentCode
Type
xs:string
none
echeck
instant
PaymentDate Time/date stamp of payment
xs:dateTime
Transaction-
specific
GrossAmount The final amount charged, including any shipping
and taxes form your Merchant Profile.
ebl:BasicAmountTyp
e
Transaction-
specific
FeeAmount PayPal fee amount charged for the transaction
ebl:BasicAmountTyp
e
Transaction-
specific
SettleAmount Amount deposited in your PayPal account after a
currency conversion.
ebl:BasicAmountTyp
e
Transaction-
specific
Website Payments Pro Integration Guide June 2006 115
Authorization & Capture API
DoCapture
TaxAmount Tax charged on the transaction
ebl:BasicAmount
Type
xs:string
Transaction-
specific
ExchangeRate Exchange rate if a currency conversion occurred.
Relevant only if you are billing in the customer’s
non-primary currency. If the customer chooses to
pay with a currency other than the non-primary
currency, the conversion occurs in the customer’s
account.
Character length and limitations: a decimal
multiplier
xs:string
Transaction-
specific
PaymentStatus Status of the payment.
The status of the payment:
None: No status
Canceled-Reversal: This means a reversal has been
canceled. For example, you won a dispute with the
customer, and the funds for the transaction that was
reversed have been returned to you.
Completed: The payment has been completed, and
the funds have been added successfully to your
account balance.
Denied: You denied the payment. This happens only
if the payment was previously pending because of
possible reasons described for the PendingReason
element.
Expired: the authorization period for this payment
has been reached.
Failed: The payment has failed. This happens only
if the payment was made from your customer’s bank
account.
Pending: The payment is pending. See the
PendingReason element for more information.
Refunded: You refunded the payment.
Reversed: A payment was reversed due to a
chargeback or other type of reversal. The funds have
been removed from your account balance and
returned to the buyer. The reason for the reversal is
specified in the ReasonCode element.
Processed: A payment has been accepted.
Voided: An authorization for this transaction has
been voided.
ebl:PaymentStatus
CodeType
xs:token
None
Canceled-Reversal
Completed
Denied
Expired
Failed
Pending
Refunded
Reversed
Processed
Voided
TABLE 8.4 Response: PaymentInfoType Elements
Element Description Data Type Possible Values
Authorization & Capture API
DoCapture
116 June 2006 Website Payments Pro Integration Guide
PendingReason NOTE: PendingReason is returned in the
response only if PaymentStatus is
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.
ebl:PendingStatus
CodeType
xs:token
none
address
echeck
intl
multi-currency
verify
other
TABLE 8.4 Response: PaymentInfoType Elements
Element Description Data Type Possible Values
Website Payments Pro Integration Guide June 2006 117
Authorization & Capture API
DoAuthorization
DoAut hori zat i on
DoAuthorizationRequest is your request to authorize a customer order that can be
fulfilled within 29 days. You use DoAuthorizationRequest when you are ready to ship
goods to your customer. After you ship, you can capture funds with DoCapture.
NOTE: DoAuthorizationRequest is for use only with order authorizations, not basic
authorizations.
To use DoAuthorization you must have previously created a customer order. You can
create an order in several ways:
z With the DoExpressCheckoutPaymentRequest or DoDirectPaymentRequest
PaymentAction element set to Order.
z With a shopping cart or PayPal Website Payments transaction with the paymentaction
HTML variable set to order.
Diagram of DoAuthorization Types
The following diagram represents the composition of the DoAuthorizationRequestType
and DoAuthorizationResponseType elements. Elements required in the request are
marked with an asterisk.
FIGURE 8.2 DoAuthorization Types
Authorization & Capture API
DoAuthorization
118 June 2006 Website Payments Pro Integration Guide
DoAuthorizationRequest
Request to authorize all or part of a customer order amount.
Fields
DoAuthorizationResponse
Response to DoAuthorizationRequest.
Fields
TABLE 8.5 DoAuthorizationRequest Fields
Element Description Data Type Allowable Values Required?
TransactionID
The value of the order’s transaction identification
number returned by a PayPal product.
Character length and limits: 19 single-byte
characters maximum
xs:string
See description. Yes
Amount
Amount to authorize.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
ebl:BasicAmount
Type
See description. Yes
TransactionEnt
ity
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.
ebl:Transaction
EntityType
Order
No
TABLE 8.6 DoAuthorizationResponse Fields
Element Description Data Type Possible Values
TransactionID
An authorization identification number.
Character length and limits: 17 single-byte
characters
xs:string
See description.
Amount
The amount you specified in the request.
ebl:BasicAmount
Type
See description.
Website Payments Pro Integration Guide June 2006 119
Authorization & Capture API
DoVoid
DoVoi d
DoVoidRequest voids an order or an authorization.
IMPORTANT: The AuthorizationID value on DoVoidRequest must be the original
authorization identification number, not the value of AuthorizationID
returned by DoReauthorizationResponse.
By definition, when the authorization period expires, the authorization or reauthorization of a
transaction is implicitly voided.
NOTE: DoVoidRequest is for use with both basic and order authorizations.
Diagram of DoVoid Types
The following diagram represents the composition of the DoVoidRequestType and
DoVoidResponseType elements. Elements required in the request are marked with an
asterisk.
FIGURE 8.3 DoVoid Types
Authorization & Capture API
DoVoid
120 June 2006 Website Payments Pro Integration Guide
DoVoidRequest
Request to void a prior authorization.
Fields
DoVoidResponse
Response to DoVoidRequest.
Fields
TABLE 8.7 DoVoidRequest Fields
Element Description Data Type Allowable Values Required?
AuthorizationI
D
The value of the original authorization
identification number returned by a PayPal product.
IMPORTANT: If you are voiding a transaction that
has been reauthorized, use the ID
from the original authorization, and
not the reauthorization.
Character length and limits: 19 single-byte
characters
xs:string
See description. Yes
Note An informational note about this settlement that is
displayed to the payer in email and in his transaction
history.
Character length and limits: 255 single-byte
characters
xs:string
See description. No
TABLE 8.8 DoVoidResponse Fields
Element Description Data Type Possible Values
Authorization
ID
The authorization identification number you
specified in the request.
Character length and limits: 19 single-byte
characters
xs:string
See description.
Website Payments Pro Integration Guide June 2006 121
Authorization & Capture API
DoReauthorization
DoReaut hori zat i on
To use DoReauthorization you must have previously authorized a transaction. You can
authorize a transaction in several ways:
– From the Merchant Services tab of your PayPal merchant account.
– With the DoExpressCheckoutPaymentRequest PaymentAction element set to
Authorization.
– With a shopping cart transaction (such as one that uses PayPal Website Payments) with
the paymentaction HTML variable set to authorization.
You can invoke DoReauthorizationRequest as many times as necessary to obtain one
successful reauthorization. When DoReauthorizationResponse returns success, the
settlement period restarts, you can capture funds, but you can no longer reauthorize.
NOTE: DoReauthorizationRequest is for use only with basic authorizations, not order
authorizations.
Diagram of DoReauthorization Types
The following diagram represents the composition of the
DoReauthorizationRequestType and DoReauthorizationResponseType elements.
Elements required in the request are marked with an asterisk.
FIGURE 8.4 DoReauthorization Types
Authorization & Capture API
DoReauthorization
122 June 2006 Website Payments Pro Integration Guide
DoReauthorizationRequest
Request to use Authorization & Capture to reauthorize a transaction.
Fields
DoReauthorizationResponse
Response to DoReauthorizationRequest.
Fields
TABLE 8.9 DoReauthorizationRequest Fields
Element Description Data Type Allowable Values Required?
Authorization
ID
The value of a previously authorized transaction
identification number returned by a PayPal product.
NOTE: You can obtain a buyer’s transaction
number from the TransactionID
element of the PayerInfo structure
returned by
GetTransactionDetailsRespons
e.
Character length and limits: 19 single-byte
characters maximum
xs:string
Any previously
authorized PayPal
transaction
identification
number.
Yes
Amount Amount to reauthorize.
Limitations: Must not exceed $10,000 USD in any
currency. No currency symbol. Decimal separator
must be a period (.), and the thousands separator
must be a comma (,).
cc:BasicAmount
Type
See description. Yes
TABLE 8.10 DoReauthorizationResponse Fields
Element Description Data Type Possible Values
Authorization
ID
A new authorization identification number.
Character length and limits: 19 single-byte
characters
xs:string
See description.
Website Payments Pro Integration Guide July 2006 123
A
Express Checkout API Error Codes,
Short Message, and Long Messages
Express Checkout API Errors
TABLE A.1 SetExpressCheckout API Errors
Error
Code
Short
Message Long Message Correcting This Error...
10001 Internal Error Internal Error
10001 Internal Error Transaction failed due to internal
error
10001 ButtonSource
value
truncated.
The transaction could not be
loaded
10001 Internal Error Internal Error
10004 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Transaction refused because of
an invalid argument. See
additional error messages for
details.
10004 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The transaction id is not valid
10007 Permission
denied
You do not have permissions to
make this API call
10102 PaymentActio
n of Order
Temporarily
Unavailable
PaymentAction of Order is
temporarily unavailable. Please
try later or use other
PaymentAction.
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
124 July 2006 Website Payments Pro Integration Guide
10402 Authorization
only is not
allowed for
merchant.
This merchant account is not
permitted to set PaymentAction
to Authorization. Please contact
Customer Service.
10404 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
ReturnURL is missing.
10405 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
CancelURL is missing.
10407 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Invalid buyer email address
(BuyerEmail).
10409 You're not
authorized to
access this
info.
Express Checkout token was
issued for a merchant account
other than yours.
10410 Invalid token Invalid token.
TABLE A.1 SetExpressCheckout API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Website Payments Pro Integration Guide July 2006 125
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
10411 This Express
Checkout
session has
expired.
This Express Checkout session
has expired. Token value is no
longer valid.
The token returned by
SetExpressCheckoutResponse expires
after three hours. If you attempt to send the
DoExpressCheckoutPaymentRequest
after that time, you will receive error code 10411 in
DoExpressCheckoutPaymentResponse.
If you receive this error, you must return your
customer to PayPal to approve the use of PayPal
again. Display an error message to inform the
customer that the transaction expired, and provide a
button to return to PayPal. In this situation, you are
effectively restarting the entire checkout process.
(Do not reuse the expired token value on
SetExpressCheckoutRequest.) However,
because you already know the final OrderTotal,
be sure to update the value for that element if
appropriate. You might also want to update the
values for ReturnURL and CancelURL, if
necessary.
10412 Duplicate
invoice
Payment has already been made
for this InvoiceID.
PayPal checks that InvoiceID values are unique
for any particular merchant. If you send an
InvoiceID value already associated with another
transaction in the PayPal system, PayPal returns
error code 10412.
You might not be able to correct this error during an
actual checkout. If you get this error, research why
might occur and modify your implementation of
Express Checkout to ensure that you generate
unique invoice identification numbers.
10415 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
A successful transaction has
already been completed for this
token.
PayPal allows a token only once for a successful
transaction.
Handling this error
If you determine that your customers are clicking
your “Place Order” button twice, PayPal
recommends that you disable the button after your
customer has clicked it.
10425 Express
Checkout has
been disabled
for this
merchant.
Express Checkout has been
disabled for this merchant. Please
contact Customer Service.
TABLE A.1 SetExpressCheckout API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
126 July 2006 Website Payments Pro Integration Guide
10432 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Invoice ID value exceeds
maximum allowable length.
10433 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Value of OrderDescription
element has been truncated.
10434 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Value of Custom element has
been truncated.
10436 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
PageStyle value exceeds
maximum allowable length.
10437 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
cpp-header-image value exceeds
maximum allowable length.
TABLE A.1 SetExpressCheckout API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Website Payments Pro Integration Guide July 2006 127
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
10438 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
cpp-header-image value exceeds
maximum allowable length.
10439 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
cpp-header-image value exceeds
maximum allowable length.
10440 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
cpp-header-image value exceeds
maximum allowable length.
10537 Risk Control
Country Filter
Failure
The transaction was refused
because the country was
prohibited as a result of your
Country Monitor Risk Control
Settings.
10538 Risk Control
Max Amount
Failure
The transaction was refused
because the maximum amount
was excceeded as a result of your
Maximum Amount Risk Control
Settings.
10539 Payment
declined by
your Risk
Controls
settings:
PayPal Risk
Model.
Payment declined by your Risk
Controls settings: PayPal Risk
Model.
TABLE A.1 SetExpressCheckout API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
128 July 2006 Website Payments Pro Integration Guide
10725 Shipping
Address
Country Error
There was an error in the
Shipping Address Country field
10727 Shipping
Address1
Empty
The field Shipping Address1 is
required
10728 Shipping
Address City
Empty
The field Shipping Address City
is required
10729 Shipping
Address State
Empty
The field Shipping Address State
is required
10730 Shipping
Address Postal
Code Empty
The field Shipping Address
Postal Code is required
10731 Shipping
Address
Country Empty
The field Shipping Address
Country is required
10736 Shipping
Address
Invalid City
State Postal
Code
A match of the Shipping Address
City, State, and Postal Code
failed.
TABLE A.2 GetExpressCheckoutDetails API Errors
Error
Code
Short
Message Long Message Correcting This Error...
10001 Internal Error Internal Error
10001 Internal Error Transaction failed due to internal
error
10001 ButtonSource
value
truncated.
The transaction could not be
loaded
10001 ButtonSource
value
truncated.
The transaction could not be
loaded
TABLE A.1 SetExpressCheckout API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Website Payments Pro Integration Guide July 2006 129
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
10004 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Transaction refused because of
an invalid argument. See
additional error messages for
details.
10004 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The transaction id is not valid
10004 Invalid
transaction
type
You can not get the details for
this type of transaction
10004 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The transaction could not be
loaded
10004 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The transaction id is not valid
10007 Permission
denied
You do not have permissions to
make this API call
10007 Permission
denied
You do not have permission to
get the details of this transaction
10007 Permission
denied
You do not have permissions to
make this API call
TABLE A.2 GetExpressCheckoutDetails API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
130 July 2006 Website Payments Pro Integration Guide
10408 Express
Checkout
token is
missing.
Express Checkout token is
missing.
10409 You're not
authorized to
access this
info.
Express Checkout token was
issued for a merchant account
other than yours.
10410 Invalid token Invalid token.
10411 This Express
Checkout
session has
expired.
This Express Checkout session
has expired. Token value is no
longer valid.
TABLE A.3 DoExpressCheckoutPayment API Errors
Error
Code
Short
Message Long Message Correcting This Error...
10001 Internal Error Transaction failed due to internal
error
10001 Internal Error Warning an internal error has
occurred. The transaction id may
not be correct
10001 ButtonSource
value
truncated.
The transaction could not be
loaded
10001 Internal Error Internal Error
10004 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Transaction refused because of
an invalid argument. See
additional error messages for
details.
TABLE A.2 GetExpressCheckoutDetails API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Website Payments Pro Integration Guide July 2006 131
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
10004 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The transaction id is not valid
10007 Permission
denied
You do not have permissions to
make this API call
10406 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The PayerID value is invalid.
10408 Express
Checkout
token is
missing.
Express Checkout token is
missing.
10409 You're not
authorized to
access this
info.
Express Checkout token was
issued for a merchant account
other than yours.
10410 Invalid token Invalid token.
10411 This Express
Checkout
session has
expired.
This Express Checkout session
has expired. Token value is no
longer valid.
10412 Duplicate
invoice
Payment has already been made
for this InvoiceID.
TABLE A.3 DoExpressCheckoutPayment API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
132 July 2006 Website Payments Pro Integration Guide
10413 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The totals of the cart item
amounts do not match order
amounts.
If you include any of the following element values
with DoExpressCheckoutPayment, the sum
of their values must equal the value of
OrderTotal.
z ItemTotal
z ShippingTotal
z HandlingTotal
z TaxTotal
If you get this error, research why it might have
occurred and modify your implementation of
Express Checkout to ensure proper addition of the
values.
10414 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The amount exceeds the
maximum amount for a single
transaction.
10415 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
A successful transaction has
already been completed for this
token.
10416 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
You have exceeded the
maximum number of payment
attempts for this token.
You can send a maximum of 10
DoExpressCheckoutPayment API calls for
any single token value, after which the token
becomes invalid.
TABLE A.3 DoExpressCheckoutPayment API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Website Payments Pro Integration Guide July 2006 133
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
10417 Transaction
cannot
complete.
The transaction cannot complete
successfully. Instruct the
customer to use an alternative
payment method.
It is possible that the payment method the customer
chooses on PayPal might not succeed when you
send DoExpressCheckoutPayment. The
most likely cause is that the customer’s credit card
failed bank authorization. Another possible, though
rare, cause is that the final OrderTotal is
significantly higher than the original estimated
OrderTotal you sent with
SetExpressCheckout at Integration Point 1,
and the final OrderTotal does not pass PayPal’s
risk model analysis.
If the customer has no other PayPal funding source
that is likely to succeed,
DoExpressCheckoutPaymentResponse
returns error code 10417.
Instruct the customer that PayPal is unable to
process the payment and redisplay alternative
payment methods with which the customer can pay.
10418 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The currencies of the shopping
cart amounts must be the same.
10419 Express
Checkout
PayerID is
missing.
Express Checkout PayerID is
missing.
10420 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Express Checkout
PaymentAction is missing.
TABLE A.3 DoExpressCheckoutPayment API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
134 July 2006 Website Payments Pro Integration Guide
10421 This Express
Checkout
session
belongs to a
different
customer.
This Express Checkout session
belongs to a different customer.
Token value mismatch.
When your customer logs into PayPal, the PayPal
PayerID is associated with the Express Checkout
token. This error is caused by mixing tokens for
two different PayerIDs. The Token and
PayerID returned for any particular customer by
GetExpressCheckoutDetailsResponse
must be the same ones you send with
DoExpressCheckoutPayment.
Verify that your programs are properly associating
the Tokens and PayerIDs.
10422 Customer must
choose new
funding
sources.
The customer must return to
PayPal to select new funding
sources.
It is possible that the payment method the customer
chooses on PayPal might not succeed when you
send
DoExpressCheckoutPaymentRequest. If
the customer has a different PayPal funding source
that is likely to succeed,
DoExpressCheckoutPaymentResponse
returns error code 10422 so you can redirect the
customer back to PayPal.
10423 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
This transaction cannot be
completed with PaymentAction
of Authorization.
This error occurs if at Integration Point 1, you set
PaymentAction to Sale with
SetExpressCheckoutRequest but at
Integration Point 3, you set PaymentAction to
Authorization with
DoExpressCheckoutPayment.
PayPal does not allow this switch from Sale to
Authorization in a single checkout session.
PayPal does allow the reverse, however. You can
set PaymentAction to Authorization with
SetExpressCheckout at Integration Point 1
and switch PaymentAction to Sale with
DoExpressCheckoutPayment at Integration
Point 3.
10424 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Shipping address is invalid. If you receive this error message, PayPal
recommends that you return your customer to
PayPal to review and approve new valid funding
sources. Although this error is rare, you should
consider trapping the error to display a message to
the customer describing what happened, along with
a button or hyperlink to return to PayPal. the
chapter about best practices in
10431 Item amount is
invalid.
Item amount is invalid.
TABLE A.3 DoExpressCheckoutPayment API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Website Payments Pro Integration Guide July 2006 135
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
10432 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Invoice ID value exceeds
maximum allowable length.
10433 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Value of OrderDescription
element has been truncated.
10434 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Value of Custom element has
been truncated.
10435 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The customer has not yet
confirmed payment for this
Express Checkout session.
10441 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The NotifyURL element value
exceeds maximum allowable
length.
10442 ButtonSource
value
truncated.
The ButtonSource element value
exceeds maximum allowable
length.
TABLE A.3 DoExpressCheckoutPayment API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
136 July 2006 Website Payments Pro Integration Guide
10443 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
This transaction cannot be
completed with PaymentAction
of Order.
10444 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The transaction currency
specified must be the same as
previously specified.
10445 This
transaction
cannot be
processed at
this time.
Please try
again later.
This transaction cannot be
processed at this time. Please try
again later.
10446 Unconfirmed
email
A confirmed email is required to
make this API call.
10537 Risk Control
Country Filter
Failure
The transaction was refused
because the country was
prohibited as a result of your
Country Monitor Risk Control
Settings.
10538 Risk Control
Max Amount
Failure
The transaction was refused
because the maximum amount
was excceeded as a result of your
Maximum Amount Risk Control
Settings.
10539 Payment
declined by
your Risk
Controls
settings:
PayPal Risk
Model.
Payment declined by your Risk
Controls settings: PayPal Risk
Model.
TABLE A.3 DoExpressCheckoutPayment API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Website Payments Pro Integration Guide July 2006 137
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
10725 Shipping
Address
Country Error
There was an error in the
Shipping Address Country field
10727 Shipping
Address1
Empty
The field Shipping Address1 is
required
10728 Shipping
Address City
Empty
The field Shipping Address City
is required
10729 Shipping
Address State
Empty
The field Shipping Address State
is required
10730 Shipping
Address Postal
Code Empty
The field Shipping Address
Postal Code is required
10731 Shipping
Address
Country Empty
The field Shipping Address
Country is required
10736 Shipping
Address
Invalid City
State Postal
Code
A match of the Shipping Address
City, State, and Postal Code
failed.
TABLE A.3 DoExpressCheckoutPayment API Errors
Error
Code
Short
Message Long Message Correcting This Error...
Express Checkout API Error Codes, Short Message, and Long Messages
Express Checkout API Errors
138 July 2006 Website Payments Pro Integration Guide
Website Payments Pro Integration Guide July 2006 139
B
Direct Payment API Error Codes,
Short Message, and Long Messages
Direct Payment API Errors
TABLE B.1 Direct Payment API Errors
Error
Code
Short
Message Long Message Corrective Action
10500 Invalid
Configuration
This transaction cannot be
processed due to an invalid
merchant configuration.
Occurs when you have not agreed to the billing
agreement
10501 Invalid
Configuration
This transaction cannot be
processed due to an invalid
merchant configuration.
Occurs when the billing agreement is disabled or
inactive.
10502 Invalid Data This transaction cannot be
processed. Please use a valid
credit card.
The credit card used is expired
10504 Invalid Data This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
The CVV provide is invalid. The CVV is between
3-4 digits long
10505 Gateway
Decline
This transaction cannot be
processed.
The transaction was refused because the AVS
response returned the value of N, and the merchant
account is not able to accept such transactions.
10507 Invalid
Configuration
This transaction cannot be
processed. Please contact PayPal
Customer Service.
Your PayPal account is restricted - contact PayPal
for more information
10508 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card expiration date.
The expiration date must be a two-digit month and
four-digit year.
10509 Invalid Data This transaction cannot be
processed.
You must submit an IP address of the buyer with
each API call
10510 Invalid Data The credit card type is not
supported. Try another card type.
The credit card type entered is not currently
supported by PayPal
10511 Invalid Data This transaction cannot be
processed.
The merchant selected an value for the
PaymentAction field that is not supported
Direct Payment API Error Codes, Short Message, and Long Messages
Direct Payment API Errors
140 July 2006 Website Payments Pro Integration Guide
10512 Invalid Data This transaction cannot be
processed. Please enter a first
name.
The first name of the buyer is required for this
merchant
10513 Invalid Data This transaction cannot be
processed. Please enter a last
name.
The last name of the buyer is required for this
merchant
10519 Invalid Data Please enter a credit card. The credit card field was blank
10520 Invalid Data This transaction cannot be
processed.
The total amount and item amounts do not match
10521 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card.
The credit card entered is invalid
10523 Internal Error This transaction cannot be
processed.
None - this is a PayPal internal error
10525 Invalid Data This transaction cannot be
processed. The amount to be
charged is zero.
The merchant entered a amount of zero
10526 Invalid Data This transaction cannot be
processed. The currency is not
supported at this time.
The currency code entered is not supported
10527 Invalid Data This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is invalid
10534 Gateway
Decline
This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is currently restricted by
PayPal. Contact PayPal for more information
10535 Gateway
Decline
This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is invalid
10536 Invalid Data This transaction cannot be
processed.
The merchant entered an invoice ID that is already
associated with a transaction by the same merchant.
By default, the invoice ID must be unique for all
transactions. To change this setting, log into
PayPal or contact customer service
10537 Filter Decline This transaction cannot be
processed.
The transaction was declined by the country filter
managed by the merchant. To accept this
transaction, change your risk settings on PayPal.
TABLE B.1 Direct Payment API Errors
Error
Code
Short
Message Long Message Corrective Action
Website Payments Pro Integration Guide July 2006 141
Direct Payment API Error Codes, Short Message, and Long Messages
Direct Payment API Errors
10538 Filter Decline This transaction cannot be
processed.
The transaction was declined by the maximum
amount filter managed by the merchant. To accept
this transaction, change your risk settings on
PayPal.
10539 Filter Decline This transaction cannot be
processed.
The transaction was declined by PayPal. Contact
PayPal for more information
10540 Invalid Data The transaction cannot be
processed due to an invalid
address.
The transaction was declined by PayPal because of
an invalid address.
10541 Gateway
Decline
This transaction cannot be
processed. Please enter a valid
credit card number and type.
The credit card entered is currently restricted by
PayPal. Contact PayPal for more information
10542 Invalid Data This transaction cannot be
processed. Please enter a valid
email address.
The email address provided by the buyer is in an
invalid format
10544 Gateway
Decline
This transaction cannot be
processed.
The transaction was declined by PayPal. Contact
PayPal for more information
10545 Gateway
Decline
This transaction cannot be
processed.
The transaction was declined by PayPal because of
possible fraudulent activity. Contact PayPal for
more information
10546 Gateway
Decline
This transaction cannot be
processed.
The transaction was declined by PayPal because of
possible fraudulent activity on the IP address.
Contact PayPal for more information
10547 Internal Error This transaction cannot be
processed.
None - this is a PayPal internal error
10548 Invalid
Configuration
This transaction cannot be
processed. The merchant's
accouht is not able to process
transactions.
The merchant account attempting the transaction is
not a business account at PayPal. Check your
account settings
10549 Invalid
Configuration
This transaction cannot be
processed. The merchant's
account is not able to process
transactions.
The merchant account attempting the transaction is
not able to process Direct Payment transactions.
Contact PayPal for more information.
10550 Invalid
Configuration
This transaction cannot be
processed.
Access to Direct Payment was disabled for your
account. Contact PayPal for more information.
10552 Invalid
Configuration
This transaction cannot be
processed.
The merchant account attempting the transaction
does not have a confirmed email address with
PayPal. Check your account settings
TABLE B.1 Direct Payment API Errors
Error
Code
Short
Message Long Message Corrective Action
Direct Payment API Error Codes, Short Message, and Long Messages
Direct Payment API Errors
142 July 2006 Website Payments Pro Integration Guide
10553 Gateway
Decline
This transaction cannot be
processed.
The merchant attempted a transaction where the
amount exceeded the upper limit for that merchant
10554 Filter Decline This transaction cannot be
processed.
The transaction was declined because of a
merchant risk filter for AVS. Specifically, the
merchant has set to decline transaction when the
AVS returned a no match (AVS = N)
10555 Filter Decline This transaction cannot be
processed.
The transaction was declined because of a
merchant risk filter for AVS. Specifically, the
merchant has set to decline transaction when the
AVS returned a partial match
10556 Filter Decline This transaction cannot be
processed.
The transaction was declined because of a
merchant risk filter for AVS. Specifically, the
merchant has set to decline transaction when the
AVS was unsupported
10701 Invalid Data There's an error with this
transaction. Please enter a valid
billing address.
The billing address entered is invalid.
10702 Invalid Data There's an error with this
transaction. Please enter a valid
address1 in the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10703 Invalid Data There's an error with this
transaction. Please enter a valid
address2 in the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10704 Invalid Data There's an error with this
transaction. Please enter a valid
city in the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10705 Invalid Data There's an error with this
transaction. Please enter a valid
state in the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10706 Invalid Data There's an error with this
transaction. Please enter your
five digit postal code in the
billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10707 Invalid Data There's an error with this
transaction. Please enter a valid
country in the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10708 Invalid Data There's an error with this
transaction. Please enter a
complete billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
TABLE B.1 Direct Payment API Errors
Error
Code
Short
Message Long Message Corrective Action
Website Payments Pro Integration Guide July 2006 143
Direct Payment API Error Codes, Short Message, and Long Messages
Direct Payment API Errors
10709 Invalid Data There's an error with this
transaction. Please enter an
address1 in the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10709 Invalid Data There's an error with this
transaction. Please enter an
address1 in the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10710 Invalid Data There's an error with this
transaction. Please enter a city in
the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10710 Invalid Data There's an error with this
transaction. Please enter a city in
the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10711 Invalid Data There's an error with this
transaction. Please enter your
state in the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10712 Invalid Data There's an error with this
transaction. Please enter your
five digit postal code in the
billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10713 Invalid Data There's an error with this
transaction. Please enter a
country in the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10713 Invalid Data There's an error with this
transaction. Please enter a
country in the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10714 Invalid Data There's an error with this
transaction. Please enter a valid
billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10715 Invalid Data There's an error with this
transaction. Please enter a valid
state in the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10716 Invalid Data There's an error with this
transaction. Please enter your
five digit postal code in the
billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10717 Invalid Data There's an error with this
transaction. Please enter your
five digit postal code in the
billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
TABLE B.1 Direct Payment API Errors
Error
Code
Short
Message Long Message Corrective Action
Direct Payment API Error Codes, Short Message, and Long Messages
Direct Payment API Errors
144 July 2006 Website Payments Pro Integration Guide
10718 Invalid Data There's an error with this
transaction. Please enter a valid
city and state in the billing
address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10719 Invalid Data There's an error with this
transaction. Please enter a valid
shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10720 Invalid Data There's an error with this
transaction. Please enter a valid
address1 in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10721 Invalid Data There's an error with this
transaction. Please enter a valid
address2 in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10722 Invalid Data There's an error with this
transaction. Please enter a valid
city in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10723 Invalid Data There's an error with this
transaction. Please enter a valid
state in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10724 Invalid Data There's an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10725 Invalid Data There's an error with this
transaction. Please enter a valid
country in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10726 Invalid Data There's an error with this
transaction. Please enter a
complete shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10726 Invalid Data There's an error with this
transaction. Please enter a
complete shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10727 Invalid Data There's an error with this
transaction. Please enter an
address1 in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10727 Invalid Data There's an error with this
transaction. Please enter an
address1 in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
TABLE B.1 Direct Payment API Errors
Error
Code
Short
Message Long Message Corrective Action
Website Payments Pro Integration Guide July 2006 145
Direct Payment API Error Codes, Short Message, and Long Messages
Direct Payment API Errors
10728 Invalid Data There's an error with this
transaction. Please enter a city in
the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10728 Invalid Data There's an error with this
transaction. Please enter a city in
the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10729 Invalid Data There's an error with this
transaction. Please enter your
state in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10730 Invalid Data There's an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10731 Invalid Data There's an error with this
transaction. Please enter a
country in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10731 Invalid Data There's an error with this
transaction. Please enter a
country in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10732 Invalid Data There's an error with this
transaction. Please enter a valid
shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10733 Invalid Data There's an error with this
transaction. Please enter a valid
state in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10734 Invalid Data There's an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10735 Invalid Data There's an error with this
transaction. Please enter your
five digit postal code in the
shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10736 Invalid Data There's an error with this
transaction. Please enter a valid
city and state in the shipping
address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
TABLE B.1 Direct Payment API Errors
Error
Code
Short
Message Long Message Corrective Action
Direct Payment API Error Codes, Short Message, and Long Messages
Direct Payment API Errors
146 July 2006 Website Payments Pro Integration Guide
10744 Invalid Data This transaction cannot be
processed. Please enter a valid
country code in the billing
address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10745 Invalid Data This transaction cannot be
processed. Please enter a valid
country code in the shipping
address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10746 Invalid Data This transaction cannot be
processed. Please use a valid
country on the billing address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10747 Invalid Data This transaction cannot be
processed.
The merchant entered an IP address that was in an
invalid format. The IP address must be in a format
such as 123.456.123.456
10748 Invalid Data This transaction cannot be
processed without a Credit Card
Verification number.
The merchant's configuration requires a CVV to be
entered, but no CVV was provided with this
transaction. Contact PayPal if you wish to change
this setting
10750 Invalid Data There's an error with this
transaction. Please enter a valid
state in the shipping address.
There was a problem with a particular field in the
address. The long error message will tell you what
field is invalid
10751 Invalid Data There's an error with this
transaction. Please enter a valid
state in the billing address.
The merchant provided an address either in the
United States or Canada, but the state provided is
not a valid state in either country
10752 Gateway
Decline
This transaction cannot be
processed.
The transaction was declined by the issuing bank,
not PayPal. The merchant should attempt another
card
10754 Gateway
Decline
This transaction cannot be
processed.
The transaction was declined by PayPal. Contact
PayPal for more information
10755 Invalid Data This transaction cannot be
processed due to an unsupported
currency.
The currency code entered by the merchant is not
supported
10756 Gateway
Decline
The transaction cannot be
processed. The country and
billing address associated with
this credit card do not match.
None - this is a PayPal internal error
10758 Invalid
Configuration
There's been an error due to
invalid API username and/or
password.
The API username or password is incorrect for this
merchant
TABLE B.1 Direct Payment API Errors
Error
Code
Short
Message Long Message Corrective Action
Website Payments Pro Integration Guide July 2006 147
Direct Payment API Error Codes, Short Message, and Long Messages
Direct Payment API Errors
10759 Gateway
Decline
This transaction cannot be
processed. Please enter a valid
credit card number and type.
The transaction was declined by PayPal. Contact
PayPal for more information
10760 Invalid
Configuration
This transaction cannot be
processed. The country listed for
your business address is not
currently supported.
The merchant's country of residence listed in their
PayPal account is not currently supported to allow
Direct Payment transactions
10761 Gateway
Decline
This transaction cannot be
processed. Please check the
status of your first transaction
before placing another order.
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
10762 Gateway
Decline
This transaction cannot be
processed.
The CVV provide is invalid. The CVV is between
3-4 digits long
10763 Invalid Data This transaction cannot be
processed.
None - this is a PayPal internal error
15001 Gateway
Decline
This transaction cannot be
processed.
The transaction was rejected by PayPal because of
excessive failures over a short period of time for
this credit card. Contact PayPal for more
information
15002 Gateway
Decline
This transaction cannot be
processed.
The transaction was declined by PayPal. Contact
PayPal for more information
15003 Invalid
Configuration
This transaction cannot be
processed.
The transaction was declined because the merchant
does not have a valid commercial entity agreement
on file with PayPal. Contact PayPal for more
information.
15004 Gateway
Decline
This transaction cannot be
processed. Please enter a valid
Credit Card Verification Number.
The transaction was declined because the CVV
entered does not match the credit card.
15005 Processor
Decline
This transaction cannot be
processed.
The transaction was declined by the issuing bank,
not PayPal. The merchant should attempt another
card
15006 Processor
Decline
This transaction cannot be
processed. Please enter a valid
credit card number and type.
The transaction was declined by the issuing bank,
not PayPal. The merchant should attempt another
card
15007 Processor
Decline
This transaction cannot be
processed. Please use a valid
credit card.
The transaction was declined by the issuing bank
because of an expired credit card. The merchant
should attempt another card
TABLE B.1 Direct Payment API Errors
Error
Code
Short
Message Long Message Corrective Action
Direct Payment API Error Codes, Short Message, and Long Messages
Direct Payment API Errors
148 July 2006 Website Payments Pro Integration Guide
Website Payments Pro Integration Guide July 2006 149
C
Authorization & Capture API Error Codes,
Short Message, and Long Messages
TABLE C.1 Authorization & Capture API Error Messages
Error
Code
Short
Message Long Message
Returned By API
Call... Correcting This Error...
10001 Internal Error Internal Error
10001 Internal Error Transaction failed due to
internal error
10004 Internal Error Invalid argument
10007 Permission
denied
You do not have permissions
to make this API call
10009 Transaction
refused
Account is locked or
inactive
Retry the request at a later
time or close order.
10010 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
Invalid argument
10600 Authorization
voided.
Authorization is voided. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the order or
authorization.
10601 Authorization
expired.
Authorization has expired. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the order or
authorization.
10602 Authorization
completed.
Authorization has already
been completed.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the order or
authorization.
Authorization & Capture API Error Codes, Short Message, and Long Messages
150 July 2006 Website Payments Pro Integration Guide
10603 The buyer is
restricted.
The buyer account is
restricted.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Contact the buyer.
10604 Authorization
must include
both buyer and
seller.
Authorization transaction
cannot be unilateral. It must
include both buyer and seller
to make an auth.
DoAuthorization Review the order to ensure
customer and seller are both
PayPal members.
10605 Unsupported
currency.
Currency is not supported. DoAuthorization
DoCapture
Retry the request with a
PayPal-supported currency.
10606 Buyer cannot
pay.
Transaction rejected, please
contact the buyer.
DoAuthorization
DoCapture
DoReauthorization
Contact the buyer.
10607 Auth&Capture
unavailable.
Authorization & Capture
feature unavailable.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Contact PayPal Customer
Service
10608 Funding source
missing.
The funding source is
missing.
DoAuthorization
DoCapture
DoReauthorization
Contact the buyer.
10609 Invalid
transactionID.
Transaction id is invalid. DoAuthorization
DoCapture
DoReauthorization
DoVoid
Check the validity of the
authorization ID and
reattempt the request.
10610 Amount limit
exceeded.
Amount specified exceeds
allowable limit.
DoAuthorization
DoCapture
DoReauthorization
Reattempt the request with a
lower amount.
10611 Not enabled. Authorization & Capture
feature is not enabled for the
merchant. Contact customer
service.
DoAuthorization
DoCapture
DoReauthorization
Contact PayPal Customer
Service.
10612 No more
settlement.
Maxmimum number of
allowable settlements has
been reached. No more
settlement for the
authorization.
DoCapture Close the order.
TABLE C.1 Authorization & Capture API Error Messages
Error
Code
Short
Message Long Message
Returned By API
Call... Correcting This Error...
Website Payments Pro Integration Guide July 2006 151
Authorization & Capture API Error Codes, Short Message, and Long Messages
10613 Currency
mismatch.
Currency of capture must be
the same as currency of
authorization.
DoCapture Ensure that the currencies
are the same, and retry the
request.
10614 Cannot void
reauth.
You can void only the
original authorization, not a
reauthorization.
DoVoid Void the authorization.
10615 Cannot reauth
reauth.
You can reauthorize only the
original authorization, not a
reauthorization.
DoReauthorization Capture the reauthorization.
10616 Maximum
number of
reauthorization
allowed for the
auth is reached.
Maximum number of
reauthorization allowed for
the auth is reached.
DoReauthorization Capture or close the
authorization
10617 Reauthorizatio
n not allowed.
Reauthorization is not
allowed inside honor period.
DoReauthorization Capture the authorization ro
reauthorize outside of honor
period.
10618 Transaction
already voided
or expired.
Transaction has already been
voided or expired.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Close the orde or
authorizationr.
10619 Invoice ID
value exceeds
maximum
allowable
length.
Invoice ID value exceeds
maximum allowable length.
DoCapture Check the length of the
invoice ID and reattempt the
request.
10620 Order has
already been
voided, expired
or completed.
Order has already been
voided, expired or
completed.
DoAuthorization
DoCapture
DoVoid
Close this order.
10621 Order has
expired.
Order has expired. DoAuthorization
DoCapture
DoVoid
Close this order.
10622 Order is
voided.
Order is voided. DoAuthorization
DoCapture
DoVoid
Close this order.
TABLE C.1 Authorization & Capture API Error Messages
Error
Code
Short
Message Long Message
Returned By API
Call... Correcting This Error...
Authorization & Capture API Error Codes, Short Message, and Long Messages
152 July 2006 Website Payments Pro Integration Guide
10623 Maximum
number of
authorization
allowed for the
order is
reached.
Maximum number of
authorization allowed for the
order is reached.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Capture this order.
10624 Duplicate
invoice
Payment has already been
made for this InvoiceID.
DoAuthorization Review the invoice ID and
reattempt the request.
10625 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The amount exceeds the
maximum amount for a
single transaction.
DoAuthorization
DoCapture
DoReauthorization
Reattempt the request with a
lower amount.
10626 Risk Transaction refused due to
risk model
DoAuthorization
DoCapture
DoReauthorization
Contact the buyer.
10627 Transaction
refused
because of an
invalid
argument. See
additional error
messages for
details.
The invoice ID field is not
supported for basic
authorizations
DoAuthorization
DoReauthorization
DoVoid
The Invoice ID field can
only be used with
DoCapture.
10628 This
transaction
cannot be
processed at
this time.
Please try
again later.
This transaction cannot be
processed at this time. Please
try again later.
DoAuthorization
DoCapture
DoReauthorization
DoVoid
Retry the request at a later
time.
10629 Reauthorizatio
n not allowed.
Reauthorization is not
allowed for this type of
authorization.
DoReauthorization Use DoAuthorization to
authorize the an order.
10630 Item amount is
invalid.
Item amount is invalid. DoAuthorization
DoCapture
Check the item amount to
ensure that it is not zero or
negative.
TABLE C.1 Authorization & Capture API Error Messages
Error
Code
Short
Message Long Message
Returned By API
Call... Correcting This Error...
Website Payments Pro Integration Guide July 2006 153
Authorization & Capture API Error Codes, Short Message, and Long Messages
11094 This
authorization
cannot be
voided,
reauthorized,
or captured
against.
This authorization can only
be handled through the
marketplace which created
it. It cannot directly be
voided, reauthorized, or
captured against.
TABLE C.1 Authorization & Capture API Error Messages
Error
Code
Short
Message Long Message
Returned By API
Call... Correcting This Error...
Authorization & Capture API Error Codes, Short Message, and Long Messages
154 July 2006 Website Payments Pro Integration Guide
155
D
Country Codes
Country Code
AFGHANISTAN AF
ÅLAND ISLANDS AX
ALBANIA AL
ALGERIA DZ
AMERICAN SAMOA AS
ANDORRA AD
ANGOLA AO
ANGUILLA AI
ANTARCTICA AQ
ANTIGUA AND BARBUDA AG
ARGENTINA AR
ARMENIA AM
ARUBA AW
AUSTRALIA AU
AUSTRIA AT
AZERBAIJAN AZ
BAHAMAS BS
BAHRAIN BH
BANGLADESH BD
BARBADOS BB
BELARUS BY
BELGIUM BE
BELIZE BZ
BENIN BJ
BERMUDA BM
BHUTAN BT
BOLIVIA BO
BOSNIA AND
HERZEGOVINA
BA
BOTSWANA BW
BOUVET ISLAND BV
BRAZIL BR
BRITISH INDIAN OCEAN
TERRITORY
IO
BRUNEI DARUSSALAM BN
BULGARIA BG
BURKINA FASO BF
BURUNDI BI
CAMBODIA KH
CAMEROON CM
CANADA CA
CAPE VERDE CV
CAYMAN ISLANDS KY
CENTRAL AFRICAN
REPUBLIC
CF
CHAD TD
CHILE CL
CHINA CN
CHRISTMAS ISLAND CX
COCOS (KEELING) ISLANDS CC
COLOMBIA CO
Country Code
Country Codes
156
COMOROS KM
CONGO CG
CONGO, THE DEMOCRATIC
REPUBLIC OF THE
CD
COOK ISLANDS CK
COSTA RICA CR
COTE D'IVOIRE CI
CROATIA HR
CUBA CU
CYPRUS CY
CZECH REPUBLIC CZ
DENMARK DK
DJIBOUTI DJ
DOMINICA DM
DOMINICAN REPUBLIC DO
ECUADOR EC
EGYPT EG
EL SALVADOR SV
EQUATORIAL GUINEA GQ
ERITREA ER
ESTONIA EE
ETHIOPIA ET
FALKLAND ISLANDS
(MALVINAS)
FK
FAROE ISLANDS FO
FIJI FJ
FINLAND FI
FRANCE FR
FRENCH GUIANA GF
FRENCH POLYNESIA PF
Country Code
FRENCH SOUTHERN
TERRITORIES
TF
GABON GA
GAMBIA GM
GEORGIA GE
GERMANY DE
GHANA GH
GIBRALTAR GI
GREECE GR
GREENLAND GL
GRENADA GD
GUADELOUPE GP
GUAM GU
GUATEMALA GT
GUERNSEY GG
GUINEA GN
GUINEA-BISSAU GW
GUYANA GY
HAITI HT
HEARD ISLAND AND
MCDONALD ISLANDS
HM
HOLY SEE (VATICAN CITY
STATE)
VA
HONDURAS HN
HONG KONG HK
HUNGARY HU
ICELAND IS
INDIA IN
INDONESIA ID
IRAN, ISLAMIC REPUBLIC
OF
IR
Country Code
157
Country Codes
IRAQ IQ
IRELAND IE
ISLE OF MAN IM
ISRAEL IL
ITALY IT
JAMAICA JM
JAPAN JP
JERSEY JE
JORDAN JO
KAZAKHSTAN KZ
KENYA KE
KIRIBATI KI
KOREA, DEMOCRATIC
PEOPLE'S REPUBLIC OF
KP
KOREA, REPUBLIC OF KR
KUWAIT KW
KYRGYZSTAN KG
LAO PEOPLE'S
DEMOCRATIC REPUBLIC
LA
LATVIA LV
LEBANON LB
LESOTHO LS
LIBERIA LR
LIBYAN ARAB JAMAHIRIYA LY
LIECHTENSTEIN LI
LITHUANIA LT
LUXEMBOURG LU
MACAO MO
MACEDONIA, THE FORMER
YUGOSLAV REPUBLIC OF
MK
Country Code
MADAGASCAR MG
MALAWI MW
MALAYSIA MY
MALDIVES MV
MALI ML
MALTA MT
MARSHALL ISLANDS MH
MARTINIQUE MQ
MAURITANIA MR
MAURITIUS MU
MAYOTTE YT
MEXICO MX
MICRONESIA, FEDERATED
STATES OF
FM
MOLDOVA, REPUBLIC OF MD
MONACO MC
MONGOLIA MN
MONTSERRAT MS
MOROCCO MA
MOZAMBIQUE MZ
MYANMAR MM
NAMIBIA NA
NAURU NR
NEPAL NP
NETHERLANDS NL
NETHERLANDS ANTILLES AN
NEW CALEDONIA NC
NEW ZEALAND NZ
NICARAGUA NI
NIGER NE
Country Code
Country Codes
158
NIGERIA NG
NIUE NU
NORFOLK ISLAND NF
NORTHERN MARIANA
ISLANDS
MP
NORWAY NO
OMAN OM
PAKISTAN PK
PALAU PW
PALESTINIAN TERRITORY,
OCCUPIED
PS
PANAMA PA
PAPUA NEW GUINEA PG
PARAGUAY PY
PERU PE
PHILIPPINES PH
PITCAIRN PN
POLAND PL
PORTUGAL PT
PUERTO RICO PR
QATAR QA
REUNION RE
ROMANIA RO
RUSSIAN FEDERATION RU
RWANDA RW
SAINT HELENA SH
SAINT KITTS AND NEVIS KN
SAINT LUCIA LC
SAINT PIERRE AND
MIQUELON
PM
Country Code
SAINT VINCENT AND THE
GRENADINES
VC
SAMOA WS
SAN MARINO SM
SAO TOME AND PRINCIPE ST
SAUDI ARABIA SA
SENEGAL SN
SERBIA AND MONTENEGRO CS
SEYCHELLES SC
SIERRA LEONE SL
SINGAPORE SG
SLOVAKIA SK
SLOVENIA SI
SOLOMON ISLANDS SB
SOMALIA SO
SOUTH AFRICA ZA
SOUTH GEORGIA AND THE
SOUTH SANDWICH ISLANDS
GS
SPAIN ES
SRI LANKA LK
SUDAN SD
SURINAME SR
SVALBARD AND JAN
MAYEN
SJ
SWAZILAND SZ
SWEDEN SE
SWITZERLAND CH
SYRIAN ARAB REPUBLIC SY
TAIWAN, PROVINCE OF
CHINA
TW
TAJIKISTAN TJ
Country Code
159
Country Codes
TANZANIA, UNITED
REPUBLIC OF
TZ
THAILAND TH
TIMOR-LESTE TL
TOGO TG
TOKELAU TK
TONGA TO
TRINIDAD AND TOBAGO TT
TUNISIA TN
TURKEY TR
TURKMENISTAN TM
TURKS AND CAICOS
ISLANDS
TC
TUVALU TV
UGANDA UG
UKRAINE UA
UNITED ARAB EMIRATES AE
UNITED KINGDOM GB
UNITED STATES US
UNITED STATES MINOR
OUTLYING ISLANDS
UM
URUGUAY UY
UZBEKISTAN UZ
VANUATU VU
VENEZUELA VE
VIET NAM VN
VIRGIN ISLANDS, BRITISH VG
VIRGIN ISLANDS, U.S. VI
WALLIS AND FUTUNA WF
WESTERN SAHARA EH
Country Code
YEMEN YE
ZAMBIA ZM
ZIMBABWE ZW
Country Code
Country Codes
160
June 2006 161
Glossary
AVS
Address Verification System. A U.S. banking industry standard for confirming the postal
address or telephone number associated with a credit card.
auth
Short for “authorization.” In U.S. banking industry terminology, to electronically check the
validity of a credit card number.
With Authorization & Capture, an auth is your means to verify that a PayPal member has
sufficient funds to meet a payment obligation.
capture
The request for settlement.
checkout
The process that takes place on your website in which a buyer selects a method of payment for
an order.
PayPal Standard Checkout refers to all PayPal products for use during buyer checkout except
for PayPal Express Checkout.
CVV2
Card Verification Value, version 2. In U.S. credit card industry terminology, a three-digit code
printed on the back of a credit card to enhance fraud protection when the credit card number is
used over the Internet or telephone.
order
An end result of a checkout. An accounting description of the purchase of one or more items
the buyer has agreed to pay for.
reauth
An initially authorized transaction amount must be reauthorized if the amount of the
transaction increases more than 115% of the original authorization.
settle
Short for “settlement.” Strictly defined, the settlement is the actual movement of funds from
the buyer’s account to the merchant’s account.
Glossary
162 June 2006
void
In the context of payment processing with Authorization & Capture, to cancel a prior
reauthorization of a settlement amount.

PayPal Website Payments Pro Integration Guide

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

1
Chapter 1

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Complementary Technical Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Website Payments Pro Overview . . . . . . . . . . . . . . 17

How Website Payments Pro Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Direct Payment API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Express Checkout Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Website Payments Pro Business Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Funding Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Technical Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 The PayPal SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Get Started Quickly: Integration Center . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Chapter 2

How Express Checkout Works

. . . . . . . . . . . . . . . 23

Express Checkout Integration Points: Technical View . . . . . . . . . . . . . . . . . . . . 25 Relationship to Authorization & Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Step 1a: Customer Selects PayPal on Your Website . . . . . . . . . . . . . . . . . . . . 28 Step 1b: Integration Point 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Usage Notes About SetExpressCheckout Elements . . . . . . . . . . . . . . . . . . 29 Step 2a: Customer Approves Use of PayPal . . . . . . . . . . . . . . . . . . . . . . . . 34 Step 2b: Customer Returns to Your Website. . . . . . . . . . . . . . . . . . . . . . . . . 36 Step 2c: Integration Point 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 ReturnURL, CancelURL, and the Express Checkout Token . . . . . . . . . . . . . . 37 Usage Notes About GetExpressCheckoutDetails Elements . . . . . . . . . . . . . . . 37 Step 3a: Customer Completes Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Step 3b: Integration Point 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Usage Notes About DoExpressCheckoutPaymentRequest Elements . . . . . . . . . 41 Step 4: Customer Notified Order Is Complete . . . . . . . . . . . . . . . . . . . . . . . . 44

July 2006

3

. 76 SetExpressCheckoutRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Button Placement Business Rules for Express Checkout Shortcut . . . . . . . . . . . . . . . . . 64 Sending Shipping Address Information to PayPal . . . . . . . . . . . . 57 Voiding Basic Authorizations. . . . . . . . . . . . 75 SetExpressCheckout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Reapproving PayPal at Integration Point 3 . . . . . . . . . . . . . 57 Chapter 5 Design Choices for Best Buying Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 GetExpressCheckoutDetailsRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 GetExpressCheckoutDetailsResponse . . . . . . . . . . . . . . . . . . . . . . . . . 77 SetExpressCheckoutResponse . . 84 4 July 2006 . . . . 47 Chapter 4 How Authorization & Capture Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Edit Shipping. . . . . . . . . . . . . . . . . . . . . . . 67 Move Important Fields to End of Checkout . . . . . . . . . . . . . . . . . . . 56 Buyer Approval for Basic Authorizations. . 64 Treatment When PayPal Is Selected . . . . . . . . . 83 Diagram of GetExpressCheckoutDetails Types . . . . . . . . . . 82 GetExpressCheckoutDetails . . . . . . . . . . . 45 Technical Overview . . 50 Order Authorizations Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Contents Chapter 3 How Direct Payment API Works . . . . . . . 62 Button Placement Business Rules for Express Checkout Mark . . . . . . . . . . . . . . . . . . . . . . 46 Relationship to Authorization & Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Best Buying Experience in Shortcut or Mark Implementations . 70 Allow the Customer to Confirm Before Calling DoExpressCheckoutPayment. 76 Diagram of Set ExpressCheckout Types . . . . . . . . . . 60 Implementation Point A: Express Checkout Shortcut . . . . . . . . . . . . . . . . . . . . 75 PayPal-supported Currencies . . . . . . . . . . . . . 56 Capturing Funds on Basic Authorizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Best Buying Experience in Shortcut Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Use the Information Returned by PayPal . . . 52 Optimal Buyer Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Implementation Point B: Express Checkout Mark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Chapter 6 Express Checkout API . . . . . . . . . . . . . . . . . . . . . . . . . 49 Fundamental Authorization Process With the APIs . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .112 Diagram of DoCapture Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120 DoReauthorization . . . . . . . . . . 87 Diagram of DoExpressCheckoutPayment Types . . . . . . . . . . . . . . . . . . . . . . . . . 98 Fields . . . . . . . . . . . .119 Diagram of DoVoid Types . . . . . . . . . . . . 93 Chapter 7 Direct Payment API . . . . . . . . . . . . . 118 DoAuthorizationResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . and Long Messages139 July 2006 5 . . . . . . . . . . . 112 DoCaptureRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 DoAuthorizationRequest . . . . . . . . . . . . . . . .122 Appendix A Express Checkout API Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Contents DoExpressCheckoutPayment . . Short Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 DoCapture . . . . . . 97 Diagram of DoDirectPayment Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108 Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .123 Appendix B Direct Payment API Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120 DoVoidResponse . . . . . . . . . . . . . . .117 Diagram of DoAuthorization Types . . . . . . . . . . . . . . 89 DoExpressCheckoutPaymentResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 DoVoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 DoDirectPaymentRequest . .121 Diagram of DoReauthorization Types . . . . . 119 DoVoidRequest . . . . . . . . . 98 DoDirectPaymentResponse . . . . . . . . . . . . . . . . . . . . 114 DoAuthorization . . . . . . . . . . 87 DoExpressCheckoutPaymentRequest. . . . . . . . . . . . . . . . . . . . . . . . . . .121 DoReauthorizationRequest . . . . . . . Short Message. . . . . . . . . . . and Long Messages123 Express Checkout API Errors . .108 Chapter 8 Authorization & Capture API . . . . . . . . . . . . . . . . . . . . . . . .122 DoReauthorizationResponse . . . . . . . . . . . . . . . . . . . . 111 Funds Availability . . . . . . . . . . . 113 DoCaptureResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Short Message. . . . and Long Messages149 Appendix D Country Codes . . 155 Glossary . . . . . . . . . . . . . . .Contents Direct Payment API Errors . . . 161 6 July 2006 . . . . . . . . . . . . . . . . .139 Appendix C Authorization & Capture API Error Codes. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . 30 SetExpressCheckoutResponse Usage Notes . . . 55 Partial Capture Scenario . . 85 Response: PayerName Elements . . . . . . . . . . . . . . . 72 PayPal-supported Currencies and Currency Codes . . . 89 Request: PaymentDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . 66 SetExpressCheckoutRequest Usage Notes for “Edit Shipping” . . .1 Table 4. . . . .11 Table 6. . . . . . . .5 Table 4. . . . . . . . . . .3 Table 2. . . . . . . . . . . .1 List of Tables Table P. . Billing and Order Total Usage . . . . . . . . . . . . . . . . . . . . . . . . . 92 July 2006 7 . . . . . 84 GetExpressCheckoutDetailsResponse Fields . . . . . . . . 52 Concurrent Authorizations Scenario . 55 Complete Capture Scenario . . .6 Table 2. . . . . . . . . . . . . 53 Total Capture Hits Relative Tolerance with Open Authroziations Scenario Void Authorizations Scenario 54 . . . . . . 56 SetExpressCheckoutRequest Usage Notes: Shipping Address . . . . 51 Simple Order Scenario . .1 Table 6. . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Steps in Checkout with Direct Payment API . . . . . 52 Complex Order Scenario . . . . . . . . . . . . . .1 Table 2. . . . . . . . . . . . . . . .2 Table 4. . . . . . . . . . . .7 Table 6. . . . . . . 77 Address (Shipping Address): AddressType Elements . . . . . . . . . . . . 13 PayPal Technical Documentation . . . . . . . . . . . . . . . . . . 24 Express Checkout Program Flow-of-Control and Integration Points .9 Table 6. . . .4 Table 2. . . . . .5 Table 6. . . . . . 14 Steps in Integrating Express Checkout . . . . .10 Table 6. .2 Table 2. . . . . . . 86 Response: AddressType Fields . . . 27 SetExpressCheckoutRequest Usage Notes . . . . . . . . . . . . . . . . . . . 75 SetExpressCheckoutRequest Fields .7 Table 3. . . . . . . . . . . . . . . . . . . . . . .2 Table 6. . . . . . . . . . .4 Table 4. . 45 PayPal Products Supporting Authorization & Capture . . . . . .6 Table 4. . . . . . . . . .1 Table 4. .5 Table 2. . . . . . . . . . . . . . . . . . . . . . . . . . .1 Table 5. . . . .7 Table 4. . .6 Table 6. . . . . 86 DoExpressCheckoutPaymentRequest Fields . . . . .3 Table 6. . . . . . . . . . . . . . . . . 40 DoExpressCheckoutPaymentRequest Usage Notes . . .12 Revision History . 37 Shipping. . . . . . . . . . . . . . . . . . . . . . . . . .1 Table P. . . . . . . . . . . . . . .3 Table 4. . . . . . . . . . 32 GetExpressCheckoutDetailsResponse Usage Notes . . . . . . . . . . . . . . . . 82 GetExpressCheckoutDetailsRequest Fields . . . . . . . . . . . . . . 84 Response: PayerInfoType Elements . .4 Table 6. . . . . .8 Table 6. .2 Table 6. . . . . .2 Table 2. 81 SetExpressCheckoutResponse Fields . .8 Table 5. 90 Request: ShipToAddress: AddressType Fields . . . . . . . . . . . . .

. .1 Table 7. . . . . . . . . . . . . . . . .4 Table 7. . . . . . . .10 Table 7. . . . . . . . . . . . . . . . . . . . . . . . . . 94 DoDirectPaymentRequest Fields . . . . . . . . . . . . . . . . . . . .1 Table 8. . . . 94 Response: PaymentInfoType Elements . . .15 Table 7. . . 114 Response: PaymentInfoType Elements . . . . . . . . . . . . .120 DoVoidResponse Fields . . . .8 Table 8. . . . . . . . . .128 DoExpressCheckoutPayment API Errors . . . . .10 Table A. . . .3 Table 7. . . . .123 GetExpressCheckoutDetails API Errors . . .1 Table A. . . . . . . . . . . . . . . . . . .102 StateOrProvince: Abbreviations for Canada and U. . .2 Table A. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 8 July 2006 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 DoCaptureRequest Fields . . . . .1 Table C. . . . 113 DoCaptureResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130 Direct Payment API Errors . . . . .2 Table 8. . .5 Table 8. . . . .100 Request: ShipToAddress: AddressType Fields . . . . . . . . .9 Table 8. .122 SetExpressCheckout API Errors . . . . . . . . 118 DoVoidRequest Fields . . . . . . . . . . . . . . . . .1 Request: PaymentDetailsItemType Fields . . . . . . . . .3 Table B. . . . . . . . .13 Table 6. . . . . . . . . . . . . . . . . . . . .107 DoDirectPaymentResponse Fields . . . . . . . . . . 93 DoExpressCheckoutPaymentResponse Fields . . . . . . . .3 Table 8. . . . . . .11 Table 8. . . . .103 Request: PaymentDetailsItemType Fields . . . . . . . . .6 Table 8. . . .106 CardOwner: PayerInfoType Fields . .6 Table 7. . . . .109 CVV2 Response Codes . . . . . . . . . . . . .8 Table 7. . .5 Table 7. . . . . . .109 Authorization & Capture API Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 Table 6. . . . . and Types of Authorization . . . . . . . . . . .7 Table 7. . . . . . . . . . . . . . .120 DoReauthorizationRequest Fields . . . . . . . . .4 Table 8.7 Table 8.139 Authorization & Capture API Error Messages . Purposes. . .108 AVS Response Codes . . . . . . . . . . . . . . . . . 98 CreditCardDetailsType Fields . . . . . 99 Request: PaymentDetailsType Fields . . . . . . . . . . . . . . . . . . . . .2 Table 7. . . .List of Tables Table 6. . . . . . . . . . . . . . . . . . . . .S. . . . . . .106 CardOwner: AddressType Fields .9 Table 7. . . . . . . . . 118 DoAuthorizationResponse Fields . .122 DoReauthorizationResponse Fields . . . . . . . 114 DoAuthorizationRequest Fields . . . . . .

2 Figure 6. . . . . . . . .5 Figure 2. . . .3 Figure 7. . . . . . . . . . . . . . 97 DoCapture Types . 65 Example of Optimal Order Review Page after Return from PayPal 67 Example of Optimal Shipping Method Page .6 Figure 2. . 34 . . .10 Figure 3. . . . .9 Figure 2. 29 . .1 Figure 6. . . . . . . 63 Payment Methods in Horizontal Design . . . . . . . . . .4 Figure 5. 64 Example of Billing Information Page with PayPal Selected . . 17 .7 Figure 2. . 83 . . .3 Figure 2. . . . . . . . . 71 . .5 Figure 5. . . . . . . . . . . . . . 76 . 69 Example of Edit Shipping Button Treatment Example Message for Reapproving PayPal SetExpressCheckout Types GetExpressCheckout Types . .3 Figure 5. . . . . . . . 112 Website Payments Pro Integration Guide July 2006 9 . . . . .2 Figure 2. . . . . . .6 Figure 5. . . . . . . . . .2 Figure 4. . . . . . . . 26 Generalized Customer Checkout .1 Figure 8. . . . . 46 . . 35 Express Checkout Integration Point 2 Example of Order Review Page Example of Order Complete Page Express Checkout Integration Point 3 . . . . . . . . . . . 44 . . 50 . . . . . . . . . 59 Example of Button Placement for Express Checkout Shortcut Placement of Express Checkout Mark Implementation . . . . . . . . . . . . . . . . .12 Figure 6. . . . .8 Figure 2. . . . . . . . . . . . . . . . . . . . . . . . . . . .2 Figure 5. . . . . . . . .1 Figure 2. . . .4 Figure 2. . . . . . . . .1 Figure 5.9 Figure 5. . 64 Payment Methods as Drop-Down SELECT List . .7 Figure 5. . 68 Example of Optimal Billing Page . . . . . . . .1 List of Figures Figure 1. . . . 62 Example of Button Placement for Express Checkout Mark . . . . . .1 Figure 2. . 36 . . . . . . . . . . . . . . . 88 DoExpressCheckoutPayment Types DoDirectPayment Types . . 60 Generalized Customer Checkout with Direct Payment API .1 High-Level View of Website Payments Pro .10 Figure 5. . . . . . 39 . . . . . . . .11 Figure 5. . . .8 Figure 5. . . . . . . .1 Figure 3. . . 41 PayPal Review Page . . . .1 Figure 5. . . . . . . . . . . . . . . . . . . . . . . . 45 PayPal Direct Payment Integration Point: Technical View Fundamental Authorization & Capture Process with APIs Implementation Points A and B . . . 23 Express Checkout Integration Points: Technical View PayPal Express Checkout Button Before Shipping Address Information 28 Express Checkout Integration Point 1 PayPal Login Page . . . . . . . . . . . 73 . . . . .

. . . . 119 DoReauthorization Types 10 July 2006 Website Payments Pro Integration Guide . . . . . . . . . 117 . . . . . . . .4 DoAuthorization Types . . . . . . . . . . .List of Figures Figure 8. . . . . . . . .3 Figure 8. . . . . . . . . . . . . . . .2 Figure 8. . . . . . 121 DoVoid Types . .

” presents a more in-depth technical overview of how the Direct Payment API works. such as security and authentication basics The location of PayPal’s Web Services Definition Language (WSDL) and X-Schema Definition files The structure of SOAP requests and responses Other APIs. Chapter 4.” is a detailed. “How Express Checkout Works. Website Payments Pro Integration Guide July 2006 11 . such as GetTransactionDetails and TransactionSearch Organization of This Document Chapter 1. Chapter 6. Intended Audience This document is written for merchants who use either PayPal Direct Payment or PayPal Express Checkout and the programmers who implement these products on a merchant’s website. Chapter 5. who can use it. “Direct Payment API” details the required and optional elements of all SOAP requests and responses for PayPal Direct Payment. variations on those guidelines. supercedes the previous release issued in May.Preface This Document This release of the Website Payments Pro Integration Guide. a document that describes PayPal Direct Payment and PayPal Express Checkout as payment solutions for customer checkout on your website. “How Authorization & Capture Works. and why it is the perfect checkout solution for your website. Chapter 7. Background Information about the PayPal Web Services API Consult the PayPal Web Services API Reference for information about the following: Architecture of the PayPal Web Services API. and special considerations in integrating Express Checkout in some cases of the customer experience. Chapter 2. “Website Payments Pro Overview. “How Direct Payment API Works. “Express Checkout API” details the required and optional elements of all SOAP requests and responses for PayPal Express Checkout. “Design Choices for Best Buying Experience. what developers need to know to make it work. 2006. such as handling shipping addresses and reapproving the use of PayPal.” details guidelines for placing PayPal logo graphics on your website.” details how Authorization & Capture works. Chapter 3. step-by-step explanation of how Express Checkout works and how it can be integrated into your checkout process.” describes what Website Payments Pro is.

Notational Conventions This document uses typefaces to identify the characteristics of text. Serif bold San-serif oblique User interface names. Example: For example. Components of Internet protocol requests and responses. Such names are used for functions. amount is the variable for a single-item shopping cart. amount_3 is the item amount for the third item in a multiple-item shopping cart. Placeholders indicate values or names that the reader should provide. Code-related names that appear in body text frames. xxxxxx xxxxxx 12 July 2006 Website Payments Pro Integration Guide .Preface Chapter 8. such as HTTPS and FORM variables. “Authorization & Capture API” details the required and optional elements of all SOAP requests and responses for Authorization & Capture. 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. For example: AbstractResponseType is the SOAP response type definition on which all PayPal API response methods are based. For example: On the Profile page. and fields. arguments. To convey additional information. These typefaces and the characteristics they imply are described below: Typeface serif italics How Used A document title. such as window names or menu selections. monospaced Pathnames or file names that appear in body text frames. data structures. A term being discussed or defined. click Email to confirm your email address. such as sending mail. For example: A file is a readable or writable stream of characters … Boolean values (not keywords). Placeholders used in the context of a format or programming standard or formal descriptions of PayPal system syntax. but amount_X is the name of the variable for a multi-item shopping cart. this document may also apply color and underlining to words or phrases that use the typefaces described above. callbacks. For example: The function returns true if it encounters an error. Hypertext link to a URL or that initiates a web action. such as txn_type. For example: The PayPal system uses a method=POST request to return IPN status variables related to subscriptions.

Website Payments Pro Integration Guide July 2006 13 .1 Revision History Date July 2006 May 2006 March 2006 January 2006 December 2005 Description Direct Payment API now supports the Switch and Solo credit cards and can be used with any PayPal-supported currency. Miscellaneous updates Miscellaneous corrections Additional API error messages for Express Checkout: 10445. Complementary Technical Documentation All PayPal technical documentation is listed here.Preface Complementary Technical Documentation Documentation Problems If you discover any errors in or have any problems with this documentation. TABLE P. Removed erroneous description that stated that the SetExpressCheckoutRequest field cpp-header-image must be URL-encoded. please e-mail us by following the instructions below. Click Email PayPal Technical Support.paypal. To contact Developer Technical Support about documentation problems: Log in to your account at https://developer. and the page number or page range. Describe the error or problem as completely as possible and give us the document title. the date of the document (located at the foot of every page). Complete the form.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. Revision History Revision history for PayPal Website Payments Pro Integration Guide. The description of each guide indicates its subject matter and documentation necessary for effective use of the guide. 10446.

https://www. https://www. https://www.p df Details use of Express Checkout and Direct Payment APIs.com/en_US/pdf/PP_OrderManagement_IntegrationGuide.pdf Details use of Express Checkout API.pdf Prerequisites None Express Checkout Integration Guide Website Payments Standard Integration Guide Website Payments Standard Integration Guide Website Payments Standard Integration Guide Website Payments Pro Integration Guide API Reference Website Payments Standard Integration Guide Website Payments Pro Integration Guide Authorization & Capture Integration Guide Order Management Integration Guide Details Instant Payment Notification (IPN) and Payment Data Transfer (PDT) for automated receipt of payment information after payment completion. pdf 14 July 2006 Website Payments Pro Integration Guide .Preface Complementary Technical Documentation TABLE P.com/en_US/pdf/PP_WebsitePaymentsStandard_Integratio nGuide. Details IPN HTML FORM variables and their meanings.paypal. Also includes information about Downloadable History Logs. Account Profile settings for variations on basic payment process.com/en_US/pdf/PP_ExpressCheckout_IntegrationGuide.com/en_US/pdf/PP_WebsitePaymentsPro_IntegrationGui de.pdf Details use of PayPal website and API for authorization and capture. https://www. PayPal placement on merchants' websites and related business rules. relates Authorization & Capture to Express Checkout and Direct Payment.com/en_US/pdf/PP_AuthCapture_IntegrationGuide.2 PayPal Technical Documentation Guide Title Website Payments Standard Integration Guide Description Details basic PayPal payment process for shopping cart and single-item purchase. HTML FORM variables for control of payment process.paypal. Customization of PayPal's payment pages.paypal.paypal. https://www.paypal. PayPal placement on merchants' websites and related business logic.

pdf Prerequisites Website Payments Standard Integration Guide Website Payments Pro Integration Guide Authorization & Capture Integration Guide Sandbox User Guide API Reference All other PayPal guides for an understanding of how products work None Sandbox User Guide Describes the PayPal Sandbox testing environment for testing website payments and Web Services APIs. and error messages.com/en_US/pdf/PP_SDK_ClassicASP_Guide.com/en_US/pdf/PP_APIReference. Microsoft Classic ASP. https://www. their SOAP structures.paypal.com/en_US/pdf/VT_user_guide.com/en_US/pdf/subscriptions.NET.com/en_US/pdf/PP_Sandbox_UserGuide.paypal. Location of PayPal WSDL and XSD files.pdf Web Services API Reference Subscriptions and Recurring Payments Guide Virtual Terminal User Guide Website Payments Standard Integration Guide None Website Payments Pro Integration Guide July 2006 15 .pdf https://www.2 PayPal Technical Documentation Guide Title Java SDK Guide .paypal.pdf Describes HTML FORM variables for using PayPal for subscriptions to goods and services.pdf https://www.pdf https://www.paypal. and PHP to simplify use of the PayPal Web Services API.paypal.com/en_US/pdf/PP_SDK_Java_Guide.pdf Details how to use the virtual terminal to accept credit card payments. Details how to get PayPal API digital certificates.com/en_US/pdf/PP_SDK_PHP_Guide.paypal. https://www. https://www. Microsoft .paypal.pdf Field-by-field description of all PayPal Web Services APIs. https://www.paypal.Preface Complementary Technical Documentation TABLE P.NET SDK Guide Classic ASP Guide PHP SDK Guide Description Details the use of the PayPal Software Development Kits for Java.com/en_US/pdf/PP_SDK_NET_Guide. https://www.

Preface Complementary Technical Documentation 16 July 2006 Website Payments Pro Integration Guide .

whether it is one page or has multiple steps. PayPal Express Checkout allows PayPal account holders to check out fast with saved information. Direct Payment API enables you to accept credit card payments directly on your website. Website Payments Pro has the flexibility to work with your unique checkout process. It is an all-in-one payment solution that includes PayPal Direct Payment API and PayPal Express Checkout. How Website Payments Pro Works Figure 1.” is an example of a standard checkout process.1 Website Payments Pro Overview With Website Payments Pro. FIGURE 1. N O T E : Express Checkout works with any of the PayPal-supported currencies. you get the payment processing capabilities of a merchant account and gateway – plus much more. PayPal remains invisible. Website Payments Pro Integration Guide July 2006 17 . so you control the customer experience. “High-Level View of Website Payments Pro.1. N O T E : The only currency supported by Direct Payment at this time is US dollars (USD).1 High-Level View of Website Payments Pro After selecting products to purchase. and enables you to gain incremental sales from PayPal’s growing base of users. your customer chooses whether they want to pay using PayPal or pay with credit cards directly on your website.

If your customer chooses to use PayPal. they purchase more. Express Checkout allows customers the option to pay quickly through PayPal – and gives your business more benefits: Give buyers more convenience. so they buy more. the more they'll buy. This gives you more advertising opportunities. and is returned to your website to complete his purchase. See “Website Payments Pro Business Rules” on page 19. Complete sales on your website. he is transferred to PayPal to login and select a shipping address and payment method. Within seconds. while working with a single provider that processes and manages all of your online payments for you. and provides you with industry-standard AVS and CVV2 responses for each transaction. Buyers prefer to pay with PayPal because their customer information is kept safe. transaction amount. Express Checkout Overview The more convenient it is for your customers to buy from you.Website Payments Pro Overview Direct Payment API Overview If your customer pays using credit cards on your website. You are required to use Direct Payment API and Express Checkout together as part of the Website Payments Pro solution. IMPO RTANT: Direct Payment API is not a standalone product. 18 July 2006 Website Payments Pro Integration Guide . they save time by completing transactions in fewer steps. Additionally. the API returns a confirmation that the transaction has been processed. Direct Payment API Overview The Direct Payment API offers you direct credit card payment processing capability through PayPal. By integrating Direct Payment API with Express Checkout as part of the Website Payments Pro solution. and get more sales. credit card information. Once the buyer completes their order. For credit card transactions. you receive your payment in seconds. Buyers finish their orders on your website. When they’re confident about the security of their information. you can accept all major payment types. and get more upsell opportunities. The Direct Payment API is not covered by the PayPal Seller Protection Policy (SPP). including PayPal. This helps increase loyalty and sales. and item information as inputs. Direct Payment API takes the billing address. For each payment. Since your customers simply log in to use information they've already entered with PayPal. customers can stay on your website as PayPal processes the payment in the background. Direct Payment API lets you flag potentially fraudulent transactions. Help customers feel safer. PayPal processes them in the background.

com/logocenter Compatibility Website Payments Pro works with many other PayPal products. wherever other payment methods are offered. and ensure you’re eligible for coverage under PayPal’s Seller Protection Policy. Authorization & Capture. Present the PayPal mark graphic wherever other payment marks are displayed. 2. billing address. such as Instant Payment Notification. With Express Checkout. and financial information. PayPal account holders should not be required enter any of this information on your website. Display PayPal as an option along side other payment methods. See “Button Placement Business Rules for Express Checkout Shortcut” on page 60. your customers click Checkout with PayPal on your website. You must: 1. Ensure buyers make it to your final confirmation page. Downloadable History Log. See “Button Placement Business Rules for Express Checkout Mark” on page 64. as well as the correct shipping and billing address. because the information is available from their PayPal accounts. email address. and more. Present the PayPal Express Checkout button and associated messaging before requesting shipping address. where they select their payment method. Automate your internal business processes. not PayPal's. and other customer information to fulfill the order. PayPal automatically gives you the shipping address.paypal.Website Payments Pro Overview Website Payments Pro Business Rules How It Works After selecting products to purchase. 3. then are returned to your website to complete their purchase. your buyers finish their orders on your website. Be notified that the buyer's address is confirmed. N O T E : You can find this logo graphic in the PayPal logo center at the following location: https://www. so you can: Get real time notification of successful payments. Settlement System. Website Payments Pro Business Rules Website Payments Pro must be integrated on your website in the following ways. They’re transferred to PayPal. Website Payments Pro Integration Guide July 2006 19 .

you can accept all major credit and debit cards. the responses. you can accept all major credit and debit cards. The Sandbox is a simulation of PayPal’s live environment. bank transfers. The PayPal SDK uses the underlying platform’s SOAP toolkit to communicate with the PayPal API endpoint. and their data can set request parameters and read response values. and PHP is a set of tools and programs that eases application development. Technical Requirements Integrating Express Checkout API and Direct Payment API requires the knowledge of the following: SOAP-based XML SOAP API calls exchange information between PayPal and the merchant site. and PayPal balance payments. American Express. For information about the Sandbox. Microsoft .Website Payments Pro Overview Funding Sources Funding Sources With Express Checkout. For information about PayPal’s SOAP APIs see. With PayPal Direct Payment API. PayPal strongly recommends that you test your integration of Express Checkout with the Sandbox to verify its completeness. 20 July 2006 Website Payments Pro Integration Guide . SSL Certificates The PayPal Sandbox The PayPal SDK The PayPal SDK for Java.paypal. For information about the PayPal SDK.NET. the PayPal Web Services API Reference. Integrated access to the PayPal Web Services APIs is one of the main features of the PayPal SDK. below. Master Card. see the PayPal Sandbox User Guide. see https://www. The latest encryption technology ensures that data is communicated safely and securely. In addition. see information about the PayPal SDK. and Discover. Stub classes representing the requests.com/sdk. including Visa.

Visit the Integration Center at: https://www.Website Payments Pro Overview Get Started Quickly: Integration Center Get Started Quickly: Integration Center PayPal’s Integration Center at https://www.paypal.com/integration has step-by-step details for getting started with the PayPal Software Development Kits (SDKs). Website Payments Standard. Express Checkout. and more. Instant Payment Notification. Authorization & Capture.com/integration Website Payments Pro Integration Guide July 2006 21 . Website Payments Pro.paypal.

Website Payments Pro Overview Get Started Quickly: Integration Center 22 July 2006 Website Payments Pro Integration Guide .

“Generalized Customer Checkout. and 3. FIGURE 2. 2.2 How Express Checkout Works PayPal Express Checkout is a combination of the checkout process on your website. The customer then selects a shipping address and payment method and approves the use of PayPal. PayPal then returns the customer to your website to review and finalize the order.1 Generalized Customer Checkout At each Integration Point.1. This generalized checkout process. PayPal login and review pages on https://www. 1. Website Payments Pro Integration Guide July 2006 23 .paypal. and you can affect the behavior and usefulness of Express Checkout by setting optional elements. When a customer clicks Checkout with PayPal. which might differ from your own. is shown in Figure 2. you must set certain required API element values. To explain how Express Checkout works.com. 3. Your customer always starts and completes his order on your website. this chapter presents a generalized checkout process and details how Express Checkout can be implemented with it.” Each numbered step in the diagram coincides with what this guide refers to as Express Checkout Integration Points 1. The Integration Points occur in the following sequence. 2. he is transferred to PayPal to log in. and PayPal Web Services API SOAP requests/responses.

Your customer finishes the checkout process on your website. your customer clicks the Checkout with PayPal button on your website. and completes the order. (Your customer does not see this step. reviews the order. email address.How Express Checkout Works After a succinct description of the technical view of implementing Express Checkout. and PayPal sends your customer an email receipt for the payment. Integration Point 3.) The payment transaction is initiated. Integration Point 1 You make an API call to pass PayPal the transaction details. Your customer selects a shipping address and payment method stored on PayPal. such as shipping address. See Page 28 1b 29 2a 2b 2c 34 36 36 3a 3b 39 41 4 44 Express Checkout gives you the flexibility to put PayPal either first in your checkout process or on your billing page along with other payment options. This allows your customer to quickly skip entering shipping and billing information on your website. 24 July 2006 Website Payments Pro Integration Guide . Integration Point 2 Your customer is transferred back to your website. You transfer your customer to your order confirmation page. and other information needed to fulfill your order. PayPal transfers the customer via an HTTP redirect. the remainder of this chapter includes detailed steps for each of the Integration Points. When your customer places the order.1 Steps in Integrating Express Checkout Step 1a Description After selecting products to purchase. you make an API call to PayPal to request payment. You then transfer the customer to PayPal via an HTTP redirect. TABLE 2. Your customer is transferred to PayPal. Your customer clicks Continue Checkout to approve the use of PayPal and is returned to your website. You then make an API call to retrieve transaction details.

2.” Website Payments Pro Integration Guide July 2006 25 .2. For precise details about the elements in all three SOAP requests and responses. whether as the complete amount of the sale or as an authorization for a total amount that you must later process with Authorization & Capture: DoExpressCheckoutPaymentRequest. Getting details from PayPal about this customer (such as shipping address) and optionally allowing the customer to edit these details during the order review: GetExpressCheckoutDetailsRequest. “Express Checkout Integration Points: Technical View” on page 26: 1. Making the payment transaction at the end of checkout. see Chapter 6. 3. Preparatory indication to PayPal that you intend to use Express Checkout for the payment for the customer’s order: SetExpressCheckoutRequest.How Express Checkout Works Express Checkout Integration Points: Technical View E x p r e s s C h e c k o u t I n t e g r a t i o n P o i n ts : Te c h n i c a l Vie w A technical view of implementing Express Checkout is shown in Figure 2. “Express Checkout API.

How Express Checkout Works Express Checkout Integration Points: Technical View FIGURE 2.2 Express Checkout Integration Points: Technical View 26 July 2006 Website Payments Pro Integration Guide .

.. Sends SOAP request Token to retrieve your customer’s information.How Express Checkout Works Express Checkout Integration Points: Technical View TABLE 2. Returns PaymentInfo with important TransactionID value and other details about the payment. 1 Clicks Checkout with PayPal button. and CancelURL – and optional elements. and PayerID returned by GetExpressCheckoutDetailsResponse. Sends SOAP request SetExpressCheckoutRequest with the required elements – estimated OrderTotal. SetExpressCheckoutRequest as a name/value pair Adds value of element Token from to the following URL.com/cgi-bin/webscr?cmd=_express-checkout&token=value 2 Logs in to PayPal. PayPal. and redirects the user’s browser to it: https://www.. With a GET. Returns GetExpressCheckoutDetailsRequest with GetExpressCheckoutDetailsRes ponse with PayerID. redirects user’s browser to merchant’s ReturnURL with token value appended. Website Payments Pro Integration Guide July 2006 27 . OrderTotal.. Renders page in customer’s browser for the next step in checkout process. Returns SetExpressCheckoutResponse with Token and appends the values of Token and PayerID to your return URL.. such as MaxAmount. 3 Clicks “Confirm Order” button Sends SOAP request DoExpressCheckoutPaymentRequest with the required elements Token. ReturnURL. email address. shipping address. confirmed or unconfirmed status of that shipping address. and clicks Continue Checkout.2 Express Checkout Program Flow-of-Control and Integration Points Customer. and other details. Merchant. PaymentAction. approves the use of PayPal.paypal.. such as your “Order Review” page.

” FIGURE 2. “How Authorization & Capture Works. handling. and tax is not precisely known.” Step 1a: Customer Selects PayPal on Your Website PayPal recommends that you place the Express Checkout button on your website before your customers are required to enter their shipping and billing information. as shown in Figure 2. “PayPal Express Checkout Button Before Shipping Address Information. see Chapter 4. For more information about Authorization & Capture.3 PayPal Express Checkout Button Before Shipping Address Information 28 July 2006 Website Payments Pro Integration Guide .How Express Checkout Works Relationship to Authorization & Capture R e la t io ns h ip t o Authorization & Capture PayPal assumes that at the end of the checkout process.3. if shipping. you will make a final sale and payment transaction via PayPal. or if you want to upsell—you can authorize a transaction that you capture later with Authorization & Capture. If at point of sale you do not know the complete cost of the order—for example.

see “SetExpressCheckout” on page 76. Website Payments Pro Integration Guide July 2006 29 . For complete details about all elements. PayPal handles the payment verification and passes you the customer’s shipping information. PayPal returns the SetExpressCheckoutResponse. Step 1b: Integration Point 1 As shown in Figure 2.4. “Express Checkout Integration Point 1.How Express Checkout Works Step 1b: Integration Point 1 N O T E : Your customer always reviews transaction details and makes the final payment on your website. PayPal never shares your customer’s financial information with anyone. see “Sending Shipping Address Information to PayPal” on page 65. You send SetExpressCheckoutRequest to PayPal. FIGURE 2. You redirect the customer’s browser to PayPal. For information about suggested use of elements related to shipping address information. Usage Notes About SetExpressCheckout Elements The following is important usage information about some of the required or optional elements in the first SOAP request for Express Checkout.4 Express Checkout Integration Point 1 Integration Point 1 consists of the following events and actions: The customer clicks the Checkout with PayPal button.” Integration Point 1 is where you transfer a customer’s browser to PayPal to select or add a shipping address and funding source.

the value of ReturnURL can include any name/value pairs your programs require. If shipping and tax charges are known.3 SetExpressCheckoutRequest Usage Notes Required or Optional? Required Element OrderTotal Notes The total estimated cost of the order to the customer. include them in OrderTotal. PayPal uses an adjusted OrderTotal to determine which funding sources it can authorize for use by the customer. For your programmatic control on the redirect of the customer’s browser to your website. the payment will still be successfully processed.How Express Checkout Works Step 1b: Integration Point 1 TABLE 2. not from standard input. just as if the value were to be included in a FORM. your ReturnURL must expect to read from the QUERY_STRING environment variable. set MaxAmount equal to OrderTotal. if not. N O T E : If the final OrderTotal sent with the MaxAmount Optional DoExpressCheckoutPaymentRequest (the final PayPal Express Checkout API) exceeds the value of MaxAmount. If OrderTotal is the final amount. OrderTotal should be the current subtotal of the order. 30 July 2006 Website Payments Pro Integration Guide . ReturnURL Required URL to which the customer’s browser is returned after approving use of PayPal. The value of your ReturnURL must always assume GET as the FORM METHOD. MaxAmount is additional information for PayPal’s business logic to properly calculate the customer’s available funds for your unique circumstances. PayPal recommends that the value of the required ReturnURL element be the final review page on which the customer confirms the order and payment. PayPal business logic calculations account for the fact that shipping and tax will likely be added to the OrderTotal before the customer completes the purchase. That is. including shipping and tax charges. The expected maximum total amount of the complete order.

if the customer were transferred to PayPal from your shipping information page. where the customer can continue with your standard checkout process. “How Authorization & Capture Works.” Website Payments Pro Integration Guide July 2006 31 . For instance. IMPORTANT: You PaymentAction Optional cannot set PaymentAction to Sale or Order on SetExpressCheckoutRequest and then change PaymentAction to Authorization on the final PayPal Express Checkout API DoExpressCheckoutPaymentRequest. How you want to obtain payment: Sale indicates that this is a final sale for which you are requesting payment. you will need to perform an additional step in order to capture the payment. Authorization or Order indicate that this payment is subject to settlement with PayPal Authorization & Capture. see the Chapter 4.How Express Checkout Works Step 1b: Integration Point 1 TABLE 2. the CancelURL value should be the URL of your shipping information page. For more information about PayPal Authorization & Capture. PayPal recommends that the value of the required CancelURL be the original page on which the customer chose to use PayPal. If you choose this action. A PaymentAction of Authorization indicates to PayPal that the order total at the end of the customer’s checkout will not be a final sale. If the customer clicks Cancel on the PayPal website.3 SetExpressCheckoutRequest Usage Notes Required or Optional? Element Notes CancelURL Required URL to which the customer is returned if he decides not to use PayPal or if PayPal is not able to authorize the customer. PayPal redirects the customer’s browser to your shipping information page.

IMPORTANT: PayPal recommends that you provide an image from a secure (https) server. “PayPal Login Page” on page 34.5. such as an accounting tracking number or additional data needed by your programs (for example. 32 July 2006 Website Payments Pro Integration Guide . N O T E : The token expires after three hours. a session-id or other variable). If the image is not on a secure server. The image has a maximum size of 750 pixels wide by 90 pixels high. see the Website Payments Standard Integration Guide. DoExpressCheckoutPaymentResponse. Custom Optional The optional Custom element is a passthrough variable. the customer will see a message about potential security risks (a mixture of secure and insecure items). In Figure 2. TABLE 2. This message might intimidate some customers from continuing with their purchase.3 SetExpressCheckoutRequest Usage Notes Required or Optional? Element Notes cpp-headerimage Optional A URL for the image you want to appear at the top left of the payment page. the DesignerFotos image beneath the PayPal logo demonstrates how a cpp-header-image appears. For more information about custom payment pages.4 SetExpressCheckoutResponse Usage Notes Element Token Notes A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout.How Express Checkout Works Step 1b: Integration Point 1 TABLE 2. when the customer’s browser is redirected to the PayPal website. You can use this value for whatever purpose you desire. Its value is returned verbatim on the final PayPal Express Checkout API.

PayPal recommends that you use the HTTPS response 302 “Object Moved” with your URL as the value of the Location header in the HTTPS response.com/cgibin/webscr?cmd=_express-checkout&token=value_from_SetExpressCheckoutResponse Express Checkout has a varition on this redirect URL that allows you to bypass calling the second API. Ensure that you use an SSL-enabled server to prevent browser warnings about a mix of secure and insecure graphics. GetExpressCheckoutDetails. you should add the value of the Token from SetExpressCheckoutResponse as a name/value pair to the following URL.paypal.How Express Checkout Works Step 1b: Integration Point 1 Transferring Your Customer to PayPal After you receive a successful response from PayPal. and redirect your customer’s browser to it: https://www. See “Allow the Customer to Confirm Before Calling DoExpressCheckoutPayment” on page 70. Website Payments Pro Integration Guide July 2006 33 . Recommendation for Browser Redirection For redirecting the customer’s browser to the PayPal URL.

5. After the customer logs in to PayPal.” 34 July 2006 Website Payments Pro Integration Guide . The customer is redirected to the PayPal login page to enter his email and password as shown in Figure 2.” If the customer does not have a PayPal account. his email address is pre-filled to save time during login. FIGURE 2.How Express Checkout Works Step 2a: Customer Approves Use of PayPal St e p 2 a : C u s t o m e r A p p r o v e s U s e o f P a y P a l The next step after redirecting the customer’s browser to PayPal with the response token is for the customer to approve PayPal as the payment method for his purchase. he can click the Don’t have a PayPal account? Click Here link and enter his credit card information to register for a PayPal account. he needs to verify his information on the “Review Your PayPal Information” page. “PayPal Review Page. “PayPal Login Page.5 PayPal Login Page If the customer has previously been to PayPal. as shown in Figure 2.6.

6 PayPal Review Page The customer then: 1. N O T E : PayPal returns your customer to the ReturnURL specified by you in SetExpressCheckoutRequest. Clicks Pay to approve the use of PayPal. PayPal returns him to the CancelURL specified in the SetExpressCheckoutRequest. 3. If the customer clicks the Cancel button. Website Payments Pro Integration Guide July 2006 35 . or enter new ones. Returns to your website to complete the purchase. select other funding sources or shipping address already saved on PayPal.How Express Checkout Works Step 2a: Customer Approves Use of PayPal FIGURE 2. 2. Can review his default funding source and shipping address.

FIGURE 2. “Express Checkout Integration Point 2” illustrates Express Checkout Integration Point 2.How Express Checkout Works Step 2b: Customer Returns to Your Website Step 2b: Customer Returns to Your Website After the customer has selected shipping and billing information on the PayPal website. PayPal returns the GetExpressCheckoutDetailsResponse. You send the GetExpressCheckoutDetailsRequest to PayPal. After your customer has reviewed and approved his financial and shipping information. You display the next screen of your checkout process to your customer. PayPal transfers your customer to the location you specified in the ReturnURL. and done any necessary editing. PayPal then redirects the customer’s browser to your website as described in “Step 2c: Integration Point 2. he clicks Pay.” Step 2c: Integration Point 2 Figure 2. which is the customer’s approval of the use of PayPal.7.7 Express Checkout Integration Point 2 Integration Point 2 consists of the following events and actions: The customer clicks Continue Checkout on the PayPal review screen. 36 July 2006 Website Payments Pro Integration Guide . PayPal redirects his browser to the ReturnURL provided in SetExpressCheckoutRequest.

5 GetExpressCheckoutDetailsResponse Usage Notes Element Payer PayerID Notes Email address of the payer. Website Payments Pro Integration Guide July 2006 37 . FirstName LastName The payer’s name. like this: https://www. Usage Notes About GetExpressCheckoutDetails Elements The following outlines usage information for some of the important elements sent in this response. see “GetExpressCheckoutDetailsResponse” on page 84. if you set ReturnURL as follows: https://www. CancelURL.com/ourcheckout PayPal changes the value as follows: https://www. Unique PayPal customer account number. You must provide this value with DoExpressCheckoutPaymentRequest. like the following: https://www.newco.com/ourcheckout?cartid=1234 PayPal prefixes the appended token with the name/value pair delimiter. PayerStatus The payer’s PayPal account status.How Express Checkout Works Step 2c: Integration Point 2 ReturnURL. For example. TABLE 2.newco. and the Express Checkout Token PayPal appends the name/value pair token=tokenValue to the value of your ReturnURL and CancelURL. if your ReturnURL value already has name/value pairs.newco. For a list of all elements in GetExpressCheckoutDetailsResponse. you need to send the GetExpressCheckoutDetailsRequest with the Token value provided in SetExpressCheckoutResponse.newco. A value of Verified means that the customer has confirmed ownership of a bank account or has verified his account status through other means. PayPal then sends you a response with your customer’s transaction information.com/ourcheckout?cartid=1234&token=tokenvalue Once the customer arrives at this ReturnURL.com/ourcheckout?token=tokenValue Similarly.

38 July 2006 Website Payments Pro Integration Guide .5 GetExpressCheckoutDetailsResponse Usage Notes Element Address Notes The payer’s shipping address selected on PayPal.com/spp Payer’s contact telephone number. ContactPhone To protect the privacy of your customer.How Express Checkout Works Step 2c: Integration Point 2 TABLE 2. N O T E : With SetExpressCheckoutRequest.com. see “Sending Shipping Address Information to PayPal” on page 65.com/privacy. ContactPhone is returned to you only if you set this as a preference in the Website Payment Preferences of your Profile on https://www. N O T E : The terms of PayPal’s Privacy Policy allow you to use a customer’s personal information only for communications relating to the transaction. A status of Confirmed means that the shipping address matches a billing address on record with PayPal and that that billing address has been verified by AVS. on GetExpressCheckoutDetailsResponse PayPal returns the For the recommended use of elements on SetExpressCheckoutRequest for handling shipping address information that the customer enters on your website (not on PayPal). For more information about the Seller Protection Policy. Your use of a Confirmed address is one of the requirements for you to be protected by PayPal’s Seller Protection Policy (SPP). unless the customer expressly gives you permission to use the information for other purposes. see the following: https://www.paypal.paypal. such as credit card numbers. PayPal does not share billing address or financial information.paypal. For information about the PayPal Privacy Policy. Address in and set AddressOverride. if you sent PayPal an shipping address you originally sent on SetExpressCheckoutRequest. see http://www. AddressStatus The status of the customer’s shipping address.

8. or specify any other information necessary to complete the purchase.8 Example of Order Review Page PayPal recommends that you alter your order review page as follows. Website Payments Pro Integration Guide July 2006 39 . This page might be your order review page or a page on which the customer can select a shipping method. “Example of Order Review Page” on page 39 is an example of a page that has been altered to reflect these guidelines. display the next page in your checkout process. FIGURE 2. enter shipping instructions. Figure 2.How Express Checkout Works Step 3a: Customer Completes Order St e p 3 a : C u s t o m e r C o m p l e t e s O r d e r After you receive a successful GetExpressCheckoutDetailsResponse.

or enter a new address. see “AddressStatus” on page 86. display the customer’s PayPal email address provided in Express Checkout. After a successful response is sent from PayPal.How Express Checkout Works Step 3a: Customer Completes Order TABLE 2.6 Shipping. For information about AddressStatus. For other recommendations about the design of your order review page. Billing Information Section Order Total When the customer clicks the “Place Order” button. The “Edit Shipping” button should return your customer to PayPal to edit shipping information on the PayPal website. For billing information. you must display to the customer the same exact OrderTotal value that you send to PayPal in DoExpressCheckoutPaymentRequest. see “Edit Shipping” on page 70. Billing and Order Total Usage Shipping Information Section Display the shipping address supplied by PayPal. direct the customer to your order completion page to inform him that you received his order. This also ensures that PayPal can provide you with the updated AddressStatus for the new shipping address. With Express Checkout. This allows the customer to quickly select a different address that he already has stored with PayPal. 40 July 2006 Website Payments Pro Integration Guide . send DoExpressCheckoutPaymentRequest to initiate the payment.

You redirect the customer to your “Order Confirmation” page. FIGURE 2. “Express Checkout Integration Point 3” illustrates Express Checkout Integration Point 3.9. PayPal returns the DoExpressCheckoutPaymentResponse. Usage Notes About DoExpressCheckoutPaymentRequest Elements The following are important usage information about some of the required or optional elements in the final SOAP request for Express Checkout.9 Express Checkout Integration Point 3 Integration Point 3 consists of the following events and actions: The customer clicks the “Place Order” button on your website.How Express Checkout Works Step 3b: Integration Point 3 St e p 3 b : I n t e g r a t i o n P o i n t 3 Figure 2. You send the DoExpressCheckoutPaymentRequest to PayPal. Website Payments Pro Integration Guide July 2006 41 .

estimated OrderTotal you sent in the SetExpressCheckoutRequest. set PaymentAction to Sale on IMPORTANT: PayPal requires that a merchant using Express Checkout display to the customer the same amount that the merchant sends to PayPal for initial authorization in the OrderTotal element with the DoExpressCheckoutPaymentRequest API. however. Authorization or Order indicate that this payment is subject to settlement with PayPal Authorization & Capture. However. you cannot change the DoExpressCheckoutPaymentRequest. including shipping. your customer may no longer be approved to use the funding source he originally accepted. This must be the final amount of the purchase and can differ from the original. DoExpressCheckoutPaymentRequest if you SetExpressCheckoutRequest. PaymentAction Required How you want to obtain payment: Sale indicates that this is a final sale for which you are requesting payment. handling.How Express Checkout Works Step 3b: Integration Point 3 TABLE 2. PayPal includes it in the customer’s transaction receipt from PayPal and on PayPal’s Transaction Details page. and tax. If you send this information. if the difference is substantial. shipping.7 DoExpressCheckoutPaymentRequest Usage Notes Required or Optional ? Required Element OrderTotal Notes Total of the order. N O T E : PayPal does not enforce a maximum difference between the original estimated OrderTotal and the one you send on DoExpressCheckoutPaymentRequest . the sum of these four totals must equal OrderTotal. 42 July 2006 Website Payments Pro Integration Guide . handling. originally set it to Authorization on You can. If you send this information. N O T E : If you set PaymentAction to Sale or Order on PaymentAction value on SetExpressCheckoutRequest. ItemTotal ShippingTotal HandlingTotal TaxTotal Optional You can send individual order-level totals for items. and tax.

The following rules apply to the PaymentItem elements: 1. 2. If you send PaymentItem. you must also send PaymentItem.Amount. the sum of (PaymentItem.ItemTotal. you should pass your customer’s shipping address to PayPal. N O T E : PayPal recommends that.SalesTax.Amount. and might decrease the likelihood that your customer will mistakenly file a chargeback. If you allow the customer to enter or edit shipping information on your website.TaxTotal. do not pass this address back to PayPal on DoExpressCheckoutPaymentRequest. 3.SalesTax x Quantity) for all payment items must equal PaymentDetails. If you send PaymentItem. can remind your customer about the purchase details. Providing this information allows your customer to review the purchase information in his PayPal account details.Name.7 DoExpressCheckoutPaymentRequest Usage Notes Required or Optional ? Optional Element Order Description Notes The description you want to appear on the customer’s transaction receipt from PayPal and on PayPal’s Transaction Details page. the sum of (PaymentItem.How Express Checkout Works Step 3b: Integration Point 3 TABLE 2. If you send PaymentItem. Payment Details is required. ShipToAddress Optional you are using the shipping address PayPal returned to you with GetExpressCheckoutDetailsResponse.Amount x Quantity) for all payment items must equal PaymentDetails. whenever possible. IMPORTANT: If PaymentItem Name Number Amount Quantity SalesTax Payment Details ItemTotal TaxTotal Payment Item is optional . PayPal recommends that you include your order number for this purchase if one is available. they are included in the customer’s transaction receipt from PayPal and on PayPal’s Transaction Details page. Doing so helps your customer complete the checkout more quickly and allows PayPal to provide you with the shipping AddressStatus in GetExpressCheckoutDetailsResponse. Website Payments Pro Integration Guide July 2006 43 . you allow your customer to use the shipping address stored by PayPal. If you send details about each item.

10Example of Order Complete Page PayPal sends the customer an email notification with the completed transaction details of the order. PayPal recommends that you display an order completion page showing the details of the transaction.How Express Checkout Works Step 4: Customer Notified Order Is Complete St e p 4 : C u s t o m e r N o t i f i e d O r d e r I s C o m p l e t e After the customer approves the order and it completes successfully. 44 July 2006 Website Payments Pro Integration Guide . An example is shown below. FIGURE 2. You also receive an email of the payment and can view it in your Downloadable History Log or Account Overview.

3 How Direct Payment API Works PayPal Direct Payment API offers you direct credit card payment processing through PayPal.1 Generalized Customer Checkout with Direct Payment API TABLE 3. and the payment transaction is initiated. PayPal does not send your customer a recipt for the payment. To pay with a credit card. Website Payments Pro Integration Guide July 2006 45 . N O T E : The customer does not see this step. 4 You transfer your customer to your order confirmation page. as PayPal processes the payment behind the scene. your customer never leaves your website. you call a PayPal API to request payment. the customer chooses to pay with a credit card and enters the credit card number and other details. The customer reviews the order. When your customer clicks “Pay” to place the order.1 Steps in Checkout with Direct Payment API Step 1 2 3 Description On your website. FIGURE 3.

” 46 July 2006 Website Payments Pro Integration Guide . nor will the customer’s credit card statement indicate that PayPal processed th epayment. the “Pay” button on your website must send the DoDirectPaymentRequest to the PayPal Web Services API service.2 PayPal Direct Payment Integration Point: Technical View PayPal is completely invisible to your customer. PayPal does not send an email receipt to the customer. before. and after the purchase. during. see Chapter 5. “Design Choices for Best Buying Experience. FIGURE 3.How Direct Payment API Works Technical Overview Te c h n i c a l O v e r v i e w At the point of payment in the checkout process. see Chapter 7. You are required to use Direct Payment and Express Checkout together as part of the Website Payments Pro solution. “Direct Payment API. For information about these business rules. For more details about the Direct Payment API. including required information you collected from the customer. and an element that specifies whether this transaction is a final sale (complete transaction amount including shipping. such as the amount of the transaction. expiration date. browser IP address. the buyer’s credit card number. The Direct Payment API SOAP response includes a transaction identification number and other information. handling and tax) or an authorization for a final amount that you must capture later with Authorization & Capture.” IMPO RTANT: Direct Payment API is not a standalone product.

if shipping. you will make a final sale and payment transaction via PayPal.How Direct Payment API Works Relationship to Authorization & Capture Relationship to Authorization & Capture PayPal assumes that at the end of the checkout process. For more information about Authorization & Capture. or if you want to upsell—you can authorize a transaction that you capture later with Authorization & Capture. handling. see the Authorization & Capture Integration Guide. Website Payments Pro Integration Guide July 2006 47 . and tax is not precisely known. If at point of sale you do not know the complete cost of the order—for example.

How Direct Payment API Works Relationship to Authorization & Capture 48 July 2006 Website Payments Pro Integration Guide .

shipping. capture. Authorization & Capture separates the authorization of payment from the capture of the authorized payment. This topic is not discussed here. or item availability). and void funds.paypal. Authorization & Capture is for merchants who have a delayed order fulfillment process and who typically make a $1 auth at checkout. Use the Authorization & Capture Application Programming Interface (API). see the Website Payments Standard Integration Guide Website Payments Pro Integration Guide July 2006 49 .com/). which is discussed here. It enables merchants to modify the original authorization amount due to order changes occurring after the initial order is placed (such as taxes. reauthorize.4 How Authorization & Capture Works Authorization & Capture is a settlement solution that provides merchants increased flexibility in obtaining payments from their buyers. 2. Create an order or authorization with Website Payments Standard HTML and capture or void the authorization on the PayPal website (https://www. During a traditional sale at PayPal. There are two ways to use Authorization & Capture: 1. For more information about the Authorization & Capture and Website Payments Standard. This chapter discusses the authorization and capture process and provides steps to help you authorize. the authorization and capture action is completed simultaneously.

2. 50 July 2006 Website Payments Pro Integration Guide . For example.1 Fundamental Authorization & Capture Process with APIs Basic or Order Authorizations: Merchant API Client DoExpressCheckout PaymentRequest <PaymentAction> Authorization or Order </PaymentAction> for order auth for basic auth DoAuthorization Request response DoAuthorization Response DoCapture Request DoCapture Response DoReauthorization Request DoReauthorization Response DoVoid Request DoVoid Response PayPal Web Services API Service 1 1 2 3 4 Authorization & Capture starts when your buyer authorizes a payment amount during checkout. Void a previous authorization. 1. you can then use the payment’s transaction ID with Authorization & Capture APIs. After your buyer completes checkout. You can reauthorize a transaction only once. FIGURE 4. up to 115% of the originally authorized amount (not to exceed an increase of $75 USD). Honor Period and Authorization Period When your buyer approves an authorization. Authorize a higher amount. the Direct Payment API does not support order authorizations. up to 115% of the originally authorized amount (not to exceed an increase of $75 USD). you can use the Direct Payment API with the <PaymentAction> element set to Authorization.How Authorization & Capture Works Fundamental Authorization Process With the APIs F u n d a m e n ta l A u t h o r i z a t i o n P r o c e s s Wit h t h e A P I s The fundamental process for authorizing and capturing is shown below. the buyer’s balance can be placed on hold for a 29-day period to ensure the availability of the authorization amount for capture. Currently. You can: Capture either a partial amount or the full authorization amount. you can use the PayPal Express Checkout API with the <PaymentAction> element set to Authorization or Order. Similarly.

You can settle without a reauthorization from day 4 to day 29 of the authorization period. not order authorizations.com). PayPal honors 100% of authorized funds for three days. A day is defined as the start of the calendar day on which the authorization or reauthorization was made (from 12AM PST to 11:50PM PST). You must explicitly specify that a transaction is a basic or order authorization. That is. PayPal will not allow you to capture funds if the buyer’s account is restricted.How Authorization & Capture Works Fundamental Authorization Process With the APIs After a successful reauthorization. or if your account has a high restriction level.1. N O T E : You must capture and void orders and order authorizations using the Authorization & Capture APIs. or a fraudulent case occurs. “PayPal Products Supporting Authorization & Capture. you cannot process order authorizations on the PayPal website (https://www. Buyer and seller accounts cannot be closed if there is a pending (unsettled) authorization. Supported PayPal Payment Products You can use Authorization & Capture with the PayPal products listed in Table 4. PayPal applies best efforts to capture funds. However.paypal.” By default. The honor period and authorization period for authorizations is described below: If you attempt to capture funds outside the honor period. However. TABLE 4. but PayPal cannot ensure that 100% of the funds will be available after the three-day honor period. there is a possibility that funds will not be available at that time. locked.1 PayPal Products Supporting Authorization & Capture Product Website Payments Buy Now Donations Shopping carts Typical Usage paymentaction=”authorization” paymentaction=”authorization” paymentaction=”authorization” paymentaction=”authorization” PayPal Products Not Supported Authorization & Capture cannot be used with the following products: eBay checkout eCheck Gift Certificates and Coupons Subscriptions Website Payments Pro Integration Guide July 2006 51 . The PayPal website supports processing only basic authorizations. You can use Authorization & Capture only when your account has a low restriction level. these products assume that a transaction is a final sale.

3 Complex Order Scenario Action Your buyer orders 2 items from your website. Simple Order TABLE 4. DoExpressCheckoutPaymentRequest with: <PaymentAction> order </PaymentAction> DoAuthorizationRequest DoCaptureRequest <$100.How Authorization & Capture Works Order Authorizations Scenarios Instant Purchase Send Money Request Money Virtual Terminal Invoicing Order Authorizations Scenarios The following are common scenarios you will encounter when implementing order authorizations.00 API Call Running Balance Complex Order TABLE 4. You receive a response that the order has been created for a payment amount of $100. specifying the variable paymentaction=order. You capture funds in the amount of $115. the maximum amount allowed.2 Simple Order Scenario Action Your buyer orders an item from your website. API Call Running Balance 52 July 2006 Website Payments Pro Integration Guide . The order now has a “Complete” status.00.00. You request authorization for $100.00. You request an order from PayPal to authorize the payment.00> $15.

00.00. You capture authorization #3 for $35. You request authorization #1 for $75.00 for the new item selection. DoExpressCheckoutPaymentRequest with: <PaymentAction> order </PaymentAction> DoAuthorizationRequest <$100. the order now has a “Complete” status.00 DoAuthorizationRequest DoCaptureRequest <$35. You receive a response that the order has been created for a payment amount of $300.00 Concurrent Authorizations TABLE 4. Your buyer contacts you and changes an item on the order. You request authorization #1 on day 1 for $100. You request authorization #2 for $25. API Call DoExpressCheckoutPaymentRequest with: <PaymentAction> order </PaymentAction> DoAuthorizationRequest DoCaptureRequest Running Balance <$75. Because the maximum amount of funds that can be captured has been reached (115% of the original order amount). You capture funds in the amount of $80.00. You receive a response that the order has been created for a payment amount of $100. specifying the variable paymentaction=order.00> API Call Running Balance Website Payments Pro Integration Guide July 2006 53 . You request an order from PayPal to authorize the payment.00 for the keyboard. specifying the variable paymentaction=order.00> $5.00.00> $0.00> $0.00.How Authorization & Capture Works Order Authorizations Scenarios Action You request an order from PayPal to authorize the payment.00. You void authorization #2. Your buyer contacts you and upgrades to next-day shipping. You request authorization #3 for $35.00 DoAuthorizationRequest DoVoid <$25.00 from your website. You receive a response that the authorization has been created for a payment amount of $100.4 Concurrent Authorizations Scenario Action Your buyer orders 3 pieces of equipment for $300.00 on authorization #1 to accomodate for the additional shipping charges.

5 Total Capture Hits Relative Tolerance with Open Authroziations Scenario Action Your buyer orders an item from your website for $1000. You receive a response that the authorization has been created for a payment amount of $200.00 (110% relative tolerance).00. which exceeds the 115% tolerance limit of the original order.00 Total Capture Hits Relative Tolerance With Open Authorizations TABLE 4. You ship the second component. specifying the variable paymentaction=order. You request authorization #2 on day 2 for $200.00 <$200.00.00.00.00. You capture authorization #1 for $1100. DoCaptureRequest DoAuthorizationRequest $0.00 for the second component.00. Your buyer requests overnight shipping. On day 3. You request authorization #2 for $60. You receive a response that the request for authorization #2 has been declined. you capture authorization #2 for $200. You receive a response that the order has been created for a payment amount of $1000.00> DoExpressCheckoutPaymentRequest with: <PaymentAction> order </PaymentAction> DoAuthorizationRequest <$1100. Your buyer contacts you and adds another item to the order. You ship the keyboard. API Call DoCaptureRequest DoAuthorizationRequest Running Balance $0. You ship the in-stock item by overnight shipping. increasing the order total to $1160. You receive a response that the authorization has been created for a payment amount of $1100.00. You request authorization #1 for $1100.How Authorization & Capture Works Order Authorizations Scenarios Action You capture authorization #1 for $100.00> API Call Running Balance $0.00 <$60. You request an order from PayPal to authorize the payment.00.00 Void Authorizations 54 July 2006 Website Payments Pro Integration Guide .00> DoCaptureRequest $0.00.

7 Partial Capture Scenario Action Your buyer orders an item from your website.00.00. You ship the item.00. You request an order from PayPal to authorize the payment. You receive a response that the order has been created for a payment amount of $350. You receive a response that the authorization has been created for a payment amount of $100.You request authorization #1 on day 1 for $100.00 DoExpressCheckoutPaymentRequest with: <PaymentAction> order </PaymentAction> DoAuthorizationRequest <$100.00.00> API Call Running Balance Website Payments Pro Integration Guide July 2006 55 .00> Partial Capture TABLE 4. . The buyer contacts you and cancels the remaining item. You request authorization #2 on day 2 for $200. You capture authorization #1 for $100.00. You request authorization #1 on day 1 for $100.00 <$200.00. You request an order from PayPal to authorize the payment.00. specifying the variable paymentaction=order. DoExpressCheckoutPaymentRequest with: <PaymentAction> order </PaymentAction> DoAuthorizationRequest <$100.00> API Call Running Balance DoCaptureRequest DoAuthorizationRequest $0. You receive a response that the order has been created for a payment amount of $100.00. You receive a response that the authorization has been created for a payment amount of $100. You receive a response that the authorization has been created for a payment amount of $200. DoVoid $0.How Authorization & Capture Works Order Authorizations Scenarios TABLE 4. specifying the variable paymentaction=order.00. You void authorization #2.6 Void Authorizations Scenario Action Your buyer orders 2 items from your website.

You receive a response that the order has been created for a payment amount of $100. your request to capture funds may be declined.00 $50.00. You capture authorization #1 for $100.00.00.00> DoCaptureRequest $0. N O T E : The API Call Running Balance DoExpressCheckoutPaymentRequest with: <PaymentAction> order </PaymentAction> DoAuthorizationRequest <$100. not a Partial capture. 56 July 2006 Website Payments Pro Integration Guide .00. You receive a response that the authorization has been created for a payment amount of $100.00 Complete Capture TABLE 4. With CompleteType set to NotComplete on the DoCapture API. Capturing Funds on Basic Authorizations PayPal recommends that you capture funds within the honor period of three days because PayPal will honor the funds for a 3-day period after the basic authorization. specifying the variable paymentaction=order. API Call DoCaptureRequest DoCaptureRequest Running Balance $0.How Authorization & Capture Works Optimal Buyer Experience Action You ship the item. Optimal Buyer Experience This section details the best practices you should follow in using Authorization & Capture to ensure the best buying experience for your customers and getting the most from Authorization & Capture. You capture authorization #1 for $100. You request an order from PayPal to authorize the payment. If you attempt to capture funds after the three-day period and the authorization fails. You request authorization #1 on day 1 for $100.8 Complete Capture Scenario Action Your buyer orders an item from your website.00. You ship the item. you capture funds in the amount of $50.00 default for the DoCapture API is a Complete capture.00.

funds will only be honored until the end of the 29th day. which will start a new three-day honor period. Voiding the authorization unlocks the temporary hold placed on your buyer’s funding sources. and a new threeday honor period will start but not extend beyond day 29. PayPal requires that you obtain consent from the buyer at the time of purchase or at the time of capture. For example. IMPO RTANT: If you want to update any details of the purchase that change the original authorization amount. it will not extend the original authorization period past 29 days.000 USD. Voiding Basic Authorizations You should void an authorization if the authorization or reauthorization will not be used.How Authorization & Capture Works Optimal Buyer Experience After day 4 of the authorization period. if you successfully complete a reauthorization on day 29 of the authorization period. Buyer Approval for Basic Authorizations A buyer-initiated authorization allows you to capture funds from the buyer’s account up to 115% of the originally authorized amount (not to exceed an increase of $75 USD) and up to $10. You should capture funds within 24 hours after you ship your buyer’s order. Website Payments Pro Integration Guide July 2006 57 . However. you can initiate a reauthorization.

How Authorization & Capture Works Optimal Buyer Experience 58 July 2006 Website Payments Pro Integration Guide .

you call the same Express Checkout APIs.5 Or Design Choices for Best Buying Experience You have a design choice for placing PayPal buttons on your website: Implementation Point A: The Express Checkout Shortcut implementation with the button graphic at the beginning of checkout Implementation Point B: The Express Checkout Mark implementation with the button graphic before the end of checkout FIGURE 5. Website Payments Pro Integration Guide July 2006 59 .1 Implementation Points A and B Whether you choose implementation point A or B.

By placing the button before your customer is asked to enter shipping and billing information. Add the PayPal choice at the top of the first page of your checkout process before you ask for the shipping address or payment method.2 Example of Button Placement for Express Checkout Shortcut Button Placement Business Rules for Express Checkout Shortcut With the Express Checkout Shortcut implementation. In addition. this placement can increase impulse purchases.Design Choices for Best Buying Experience Implementation Point A: Express Checkout Shortcut Implementation Point A: Express Checkout Shortcut Putting PayPal first in your checkout—the Express Checkout Shortcut implementation— allows a customer to save time by skipping several checkout steps. FIGURE 5. repeat purchases. adhere to the following four business rules.2. and purchases from shoppers who are comfortable paying online only with PayPal. your customer can check out quickly using information already stored on PayPal. Following these rules helps PayPal account holders understand that they are offered the benefits of a faster checkout. “Example of Button Placement for Express Checkout Shortcut” on page 60 is an example of how to implement the Express Checkout product as the first step of your checkout process. This section details how to position PayPal at the beginning of your checkout process. Use the approved Express Checkout button You can get the Express Checkout button logo and message text from the following location: 60 July 2006 Website Payments Pro Integration Guide . Figure 5.

paypal. Pay without sharing your financial information. as described in “Implementation Point A: Express Checkout Shortcut” on page 60. Put the text following text above either the Checkout with PayPal button or the corresponding message.com/express-checkout-buttons From this location. Website Payments Pro Integration Guide July 2006 61 . whichever is most appropriate to your website design.Design Choices for Best Buying Experience Implementation Point A: Express Checkout Shortcut https://www. Secure Checkout with PayPal Put the following message next to the PayPal Express Checkout button: Save time. Fast. You might need to edit the variables in the HTML to suit your particular needs. Checkout securely. copy the HTML and paste it in the appropriate location of your checkout pages.

3. For background information about design considerations similar to this.3 Placement of Express Checkout Mark Implementation An example of PayPal’s recommended placement of PayPal with other payment methods is shown in Figure 5. The primary difference is that the customer selects PayPal from a list of other payment methods. you must redirect the customer to PayPal according the instructions described “Step 1b: Integration Point 1” on page 29. When the customer clicks the “Continue Checkout” button or hyperlink on your billing page. see “Step 1a: Customer Selects PayPal on Your Website” on page 28. FIGURE 5.” This is the point in the checkout process where PayPal can be placed with other payment methods. “Placement of Express Checkout Mark Implementation. “Example of Button Placement for Express Checkout Mark” on page 63.4.Design Choices for Best Buying Experience Implementation Point B: Express Checkout Mark I m p l e m e n ta t i o n P o i n t B : E x p r e s s C h e c k o u t M a r k The Express Checkout Mark implementation is Step 1a in Figure 5. 62 July 2006 Website Payments Pro Integration Guide .

4 Example of Button Placement for Express Checkout Mark Website Payments Pro Integration Guide July 2006 63 .Design Choices for Best Buying Experience Implementation Point B: Express Checkout Mark FIGURE 5.

com/logocenter Add the following message next to the PayPal mark logo: Save time. Customers will be confused if they are asked to enter this information after selecting PayPal. “Payment Methods in Horizontal Design.” – A drop-down SELECT list shown in Figure 5.5 Payment Methods in Horizontal Design FIGURE 5.paypal. You have several designs to choose from: – The treatment shown in “Example of Button Placement for Express Checkout Mark” on page 63 – Horizontal option fields shown in Figure 5. Display the options for payment methods before you ask the customer for billing address information. N O T E : You can find this logo graphic in the PayPal logo center at the following location: https://www.6 Payment Methods as Drop-Down SELECT List Treatment When PayPal Is Selected When your customer selects PayPal.6. you should: Use JavaScript to hide or disable credit card fields and billing address fields.” FIGURE 5. Checkout securely. PayPal recommends the following design: IMPO RTANT: The positioning of Express Checkout according to these business rules is required if you are implementing PayPal Direct Payment. Pay without sharing your financial information. 64 July 2006 Website Payments Pro Integration Guide . 1.5. Make a design choice for the display of PayPal with other payment methods. when PayPal is positioned with other payment methods.. “Payment Methods as Drop-Down SELECT List. Add the PayPal mark logo graphic as one of the options.Design Choices for Best Buying Experience Implementation Point B: Express Checkout Mark Button Placement Business Rules for Express Checkout Mark For the Express Checkout Mark implementation.

Design Choices for Best Buying Experience
Implementation Point B: Express Checkout Mark

If other fields such as coupon code or gift certificate are on the page, still display them so your customer may fill them out before being redirected to PayPal. Change the function of the “Continue Checkout” button to send the customer to PayPal according to the instructions in “Step 1b: Integration Point 1” on page 29. Near the “Continue” button or hyperlink, put an explanatory message such as the following to inform your customer what will occur when the “Continue” button or hyperlink is clicked. The text Your Company Name is the name of your business. Clicking “Continue” will transfer you to PayPal. After you approve the use of PayPal, you will be returned to Your Company Name to complete your purchase. Figure 5.7, “Example of Billing Information Page with PayPal Selected” on page 65 shows what your billing page might look like after the customer selects PayPal.
FIGURE 5.7 Example of Billing Information Page with PayPal Selected

Sending Shipping Address Information to PayPal
If you have already collected shipping address information from your customer, on the PayPal pages the customer should be able to see this shipping address information but not be able to change it. Follow these usage notes to send the shipping address to PayPal with SetExpressCheckoutRequest.

Website Payments Pro Integration Guide

July 2006

65

Design Choices for Best Buying Experience
Implementation Point B: Express Checkout Mark

For complete details about SetExpressCheckoutRequest, see “SetExpressCheckoutRequest” on page 77.

TABLE 5.1 SetExpressCheckoutRequest Usage Notes: Shipping Address Element Address Notes Customer’s street address for shipping. Your sending the customer-entered shipping Address to PayPal allows PayPal to return the address confirmation status in the AddressStatus element of GetExpressCheckoutDetailsResponse. Be sure to include the Country element as part of Address.
N O T E : The address entered by the customer on your website must exactly

match the customer’s confirmed PayPal address in order for PayPal to verify that the shipping address is confirmed. Your use of a Confirmed address is one of the requirements for you to be protected by PayPal’s Seller Protection Policy (SPP). For more information about the Seller Protection Policy, see the following: https://www.paypal.com/spp Address Override If you set AddressOverride, the Address sent on SetExpressCheckoutRequest overrides the customer’s stored address. The customer is shown the passed-in address but cannot edit it.
N O T E : If the Address is not valid (such as missing required fields, including

Country) or not included SetExpressCheckoutRequest, PayPal does not display any address to the customer.

66

July 2006

Website Payments Pro Integration Guide

Design Choices for Best Buying Experience
Best Buying Experience in Shortcut Implementation

B e s t B u y i n g E x p e r i e n c e i n S h o r t c u t I m p l e m e n ta t i o n
A key benefit of Express Checkout is that a customer can save time by skipping several checkout steps using the shipping and billing information stored on PayPal. You might have to adjust your checkout flow to avoid redundant information gathering from the customer, to make sure you gather other important information from the customer that PayPal does not supply, or to prevent “circular” pages. This section details some best practices you should consider in implementing the Express Checkout Shortcut.

Move Important Fields to End of Checkout
The pages your customer skips might ask for important information such as shipping method, delivery date, or coupon codes. In this case, PayPal recommends that you collect this information from your customer after the return to your website after Express Checkout Integration Point 2. For instance, if you ask for shipping method on your shipping address page, consider moving the fields to gather this information to your “Order Review” page. See Figure 5.8, “Example of Optimal Order Review Page after Return from PayPal” and Figure 5.10, “Example of Optimal Billing Page” on page 69.
FIGURE 5.8 Example of Optimal Order Review Page after Return from PayPal

Use the Information Returned by PayPal
If you prefer not to change your checkout flow as described in the previous section, PayPal recommends that you return your customer to the original page where your important information fields appear. Be sure to disable or hide your own shipping address, billing address, and payment method fields, and display the information that PayPal supplies you.
Example of Optimal Customer Experience

The following is a detailed example.

Website Payments Pro Integration Guide

July 2006

67

” FIGURE 5.9 Example of Optimal Shipping Method Page When your customer clicks “Continue. “Example of Optimal Shipping Method Page. after the customer has clicked Continue Checkout on PayPal. Do not ask the customer for billing address at this point because he has indicated he is using PayPal. and ask your customer to enter additional information.9.” display your billing page. such as coupon codes. display the shipping address PayPal has provided in GetExpressCheckoutDetailsResponse and display your shipping method input fields or SELECT list so your customer can select the method. return the customer to your shipping address page (this URL is the value of ReturnURL.). Show the payment method as PayPal.Design Choices for Best Buying Experience Best Buying Experience in Shortcut Implementation If you position the PayPal button at the top of your shipping address page. On your shipping address page. 68 July 2006 Website Payments Pro Integration Guide . See Figure 5.

Design Choices for Best Buying Experience Best Buying Experience in Shortcut Implementation FIGURE 5.10Example of Optimal Billing Page Website Payments Pro Integration Guide July 2006 69 .

Between the response from SetExpressCheckout and calling DoExpressCheckoutPayment. display a button labelled “Place Order” or “Pay” that the customer must click and that calls DoExpressCheckoutPayment. IMPO RTANT: You must allow the customer to confirm the payment on your website. not on PayPal. Allow the Customer to Confirm Before Calling DoExpressCheckoutPayment With Express Checkout.” shows the recommended way to implement an “Edit Shipping” button with Express Checkout.Design Choices for Best Buying Experience Best Buying Experience in Shortcut or Mark Implementations Best Buying Experience in Shortcut or Mark I m p l e m e n ta t i o n s This section details some best practices you should consider in designing either the Express Checkout Shortcut implementation or the Express Checkout Mark Implementation. “Example of Edit Shipping Button Treatment. the customer completes the order and approves the payment on your website. On your website. Edit Shipping Figure 5. These practices apply to both implementations to give your customer the best shopping experience. you must allow the PayPal user to confirm the order.11. 70 July 2006 Website Payments Pro Integration Guide .

PayPal recommends that you create an “Edit Shipping” button or hyperlink to return your customer to PayPal to change that shipping address information. You redirect your customer’s browser to PayPal. Website Payments Pro Integration Guide July 2006 71 .11Example of Edit Shipping Button Treatment If your customer selected a shipping address from his PayPal account. see “SetExpressCheckoutRequest” on page 77. The following are special considerations about implementing “Edit Shipping” function. For details about AddressStatus. The “Edit Shipping” button or hyperlink follows the same integration instructions as Integration Point 1 “Step 1b: Integration Point 1” on page 29: The customer clicks the “Edit Shipping” button or hyperlink on your order review page. This button or hyperlink allows the customer to quickly select a different address already on file with PayPal or to enter a new address. see “GetExpressCheckoutDetailsResponse” on page 84. For complete details about SetExpressCheckoutRequest. You send SetExpressCheckoutRequest to PayPal. An “Edit Shipping” button or hyperlink also ensures that PayPal can provide you with the updated AddressStatus about the new.Design Choices for Best Buying Experience Best Buying Experience in Shortcut or Mark Implementations FIGURE 5. edited shipping address. N O T E : Your customers are not asked to log in again if they have logged in to PayPal within the last five minutes. PayPal returns SetExpressCheckoutResponse.

Because your program should know the shipping and tax charges at this point. Set ReturnURL to your order review page or the page on which the customer clicked the “Edit Shipping” button or hyperlink. along with a button or hyperlink to return to PayPal. the customer is trying to cancel the editing of the shipping address. be sure to send an updated OrderTotal that includes those charges. Although this error is rare. If you receive this error message. It is likely that at this point if the customer clicks Cancel on PayPal. Set CancelURL to your order review page or the page on which the customer clicked the “Edit Shipping” button or hyperlink. PayPal recommends that you return your customer to PayPal to review and approve new. OrderTotal Required MaxAmount Optional ReturnURL Required CancelURL Required Reapproving PayPal at Integration Point 3 If the customer-selected funding sources are no longer applicable when you call DoExpressCheckoutPaymentRequest to PayPal. valid funding sources. including shipping and tax charges. The total estimated cost of the order to the customer. URL to which the customer’s browser is returned after approving use of PayPal. The expected maximum total amount of the complete order.2 SetExpressCheckoutRequest Usage Notes for “Edit Shipping” Required or Optional? Element Token Notes Optional To identify this request as part of the same checkout session. Consider displaying an error page like that shown in “Example Message for Reapproving PayPal” on page 73.Design Choices for Best Buying Experience Best Buying Experience in Shortcut or Mark Implementations TABLE 5. You should set MaxAmount at least equal to the updated OrderTotal. PayPal returns error code 10422. URL to which the customer is returned if he decides not to use PayPal. This error can occur if the final OrderTotal is significantly higher than the original OrderTotal on SetExpressCheckoutRequest. not the approval of the use of PayPal. you should consider trapping the error to display a message to the customer describing what happened. use the Token value PayPal originally returned in SetExpressCheckoutResponse after your first invocation of SetExpressCheckoutRequest. 72 July 2006 Website Payments Pro Integration Guide .

the customer is not asked to log in again. You redirect the customer ‘s browser to PayPal. Website Payments Pro Integration Guide July 2006 73 . You send SetExpressCheckoutRequest to PayPal. Special considerations for the Return to PayPal function are the same as for “Edit Shipping” on page 70. N O T E : If this redirection occurs within five minutes of the customer’s last login to PayPal.12Example Message for Reapproving PayPal For the Return to PayPal button or hyperlink.” redirect the customer’s browser to a page where he can select a new payment method. the programming is the same as for Integration Point 1: Your customer clicks the “Return to PayPal” button on your error page. If your customer clicks “Cancel use of PayPal.Design Choices for Best Buying Experience Best Buying Experience in Shortcut or Mark Implementations FIGURE 5. PayPal returns the SetExpressCheckoutResponse.

Design Choices for Best Buying Experience Best Buying Experience in Shortcut or Mark Implementations 74 July 2006 Website Payments Pro Integration Guide .

do not set currencyID to USD in one request and then to GBP in a later request for the same buyer. TABLE 6. DoExpressCheckoutPayment PayPal-supported Currencies The following currencies are supported by PayPal.6 Express Checkout API The Express Checkout API is the Website Payments Pro alternative to standard PayPal shopping cart processing. Website Payments Pro Integration Guide July 2006 75 . The Express Checkout API consists of three distinct SOAP requests that you make at the three integration points during a customer checkout: 1. For any one particular buyer’s checkout session. do not mix currencies either in any single SOAP request or across SOAP requests. GetExpressCheckoutDetails 3. For example.1 PayPal-supported Currencies and Currency Codes Code AUD CAD EUR GBP JPY USD Currency Australian Dollar Canadian Dollar Euro Pound Sterling Japanese Yen US Dollar IMPO RTANT: All currency amount fields in the three Express Checkout APIs require that the currencyID attribute be set to one of the supported currency codes. SetExpressCheckout 2.

1 SetExpressCheckout Types 76 July 2006 Website Payments Pro Integration Guide . Diagram of Set ExpressCheckout Types The following diagram represents the composition of the SetExpressCheckoutRequestType and SetExpressCheckoutResponseType elements.Express Checkout API SetExpressCheckout SetExpressCheckout SetExpressCheckout indicates to PayPal that you are using Express Checkout to obtain payment from your customer. Elements required in the request are indicated with an asterisk. FIGURE 6.

If shipping cost and tax charges are known.).Express Checkout API SetExpressCheckout SetExpressCheckoutRequest Request to use PayPal Express Checkout to obtain payment. Website Payments Pro Integration Guide July 2006 77 . and the thousands separator must be a comma (. IMPO RTANT: Any fields in the WSDL or XSD files that are not described here are ignored. include them in OrderTotal. Yes one of the three-character currency codes for any of the supported PayPal currencies. do not set CountryName.000 USD in any currency.2 SetExpressCheckoutRequest Fields Element Token Description On your first invocation of this token is returned by Data Type ebl:Express CheckoutTokenType Allowable Values See the description of “Token” on page 82. Required ? No SetExpressCheckoutRequest. if not. OrderTotal should be the current sub-total of the order. For example. the value of SetExpressCheckoutResponse.). Regardless of currency. SetExpressCheckoutReque st. for example. if you want the Character length and limitations: 20 single-byte characters OrderTotal The total cost of the order to the customer. No currency symbol. Character length and limitations: Must not exceed $10. decimal separator must be a period (. Fields TABLE 6. Equivalent to nine characters maximum for USD. I M P O R T A N T : Include this element and its value only if you want to modify an existing checkout session with another invocation of customer to edit his shipping address on PayPal. N O T E : You must set the currencyID attribute to cc:BasicAmount Type See description.

PayPal returns this value to you on xs:string See description. Yes customer chose to pay with PayPal. including shipping cost and tax charges. xs:string Character length and limitations: no limit.2 SetExpressCheckoutRequest Fields Element MaxAmount Description The expected maximum total amount of the complete order. Character length and limitations: Must not exceed $10. Order Description Description of items the customer is purchasing.). No DoExpressCheckoutPaymentResponse.000 USD in any currency. Character length and limitations: 127 single-byte alphanumeric characters ReturnURL URL to which the customer’s browser is returned after choosing to pay with PayPal. CancelURL URL to which the customer is returned if he does not approve the use of PayPal to pay you. No currency symbol. N O T E : You must set the currencyID attribute to Data Type cc:BasicAmount Type Allowable Values See description. such as a tracking number or other value you want PayPal to return on and xs:string See description. No Custom xs:string See description. Equivalent to nine characters maximum for USD. Regardless of currency. Character length and limitations: 256 single-byte alphanumeric characters InvoiceID Your own unique invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters A free-form field for your own use. No GetExpressCheckoutDetailsResponse DoExpressCheckoutPaymentResponse. decimal separator must be a period (. and the thousands separator must be a comma (. N O T E : PayPal recommends that the value of ReturnURL be xs:string See description.Express Checkout API SetExpressCheckout TABLE 6. Yes the final review page on which the customer confirms the order and payment. Required ? No one of the three-character currency codes for any of the supported PayPal currencies. N O T E : PayPal recommends that the value of CancelURL be the original page on which the See description. Character length and limitations: no limit 78 July 2006 Website Payments Pro Integration Guide .).

Express Checkout API
SetExpressCheckout TABLE 6.2 SetExpressCheckoutRequest Fields Element
Address

Description Customer’s shipping address.
N O T E : If you include a shipping address and set

Data Type
ebl:AddressType

Allowable Values See Table 6.3 on page 81.

Required ? No

the AddressOverride element on the request, PayPal returns this same address in

GetExpressCheckoutDetailsRes ponse.
ReqConfirm Shipping

The value 1 indicates that you require that the customer’s shipping address on file with PayPal be a confirmed address.
N O T E : Setting this element overrides the setting

xs:string

0 1

No

you have specified in your Merchant Account Profile. Character length and limitations: One single-byte numeric character.
NoShipping

The value 1 indicates that on the PayPal pages, no shipping address fields should be displayed whatsoever. Character length and limitations: Four single-byte numeric character. The value 1 indicates that the PayPal pages should display the shipping address set by you in the Address element on this SetExpressCheckoutRequest, not the shipping address on file with PayPal for this customer.
N O T E : Displaying the PayPal street address on file

xs:string

0 1

No

Address Override

xs:string

0 1

No

does not allow the customer to edit that address. Character length and limitations: Four single-byte numeric character.
LocaleCode

Locale of pages displayed by PayPal during Express Checkout. Character length and limitations: Five single-byte alphabetic characters, upper- or lowercase.

xs:string

AU or en_AU DE or de_DE FR or fr_FR GB or en_GB IT or it_IT JP or ja_JP US or en_US

No

Website Payments Pro Integration Guide

July 2006

79

Express Checkout API
SetExpressCheckout TABLE 6.2 SetExpressCheckoutRequest Fields Element
PageStyle

Description Sets the Custom Payment Page Style for payment pages associated with this button/link. PageStyle 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. A URL for the image you want to appear at the top left of the payment page. The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal recommends that you provide an image that is stored on a secure (https) server. Character length and limitations: 127 Sets the border color around the header of the payment page. The border is a 2-pixel perimeter around the header space, which is 750 pixels wide by 90 pixels high. Character length and limitations: Six character HTML hexadecimal color code in ASCII Sets the background color for the header of the payment page. Character length and limitation: Six character HTML hexadecimal color code in ASCII Sets the background color for the payment page. Character length and limitation: Six character HTML hexadecimal color code in ASCII

Data Type
xs:string

Allowable Values See description.

Required ? No

cpp-headerimage

xs:string

See description.

No

cpp-headerborder-color

xs:string

See description.

No

cpp-headerback-color

xs:string

See description.

No

cpp-payflowcolor

xs:string

See description.

No

80

July 2006

Website Payments Pro Integration Guide

Express Checkout API
SetExpressCheckout TABLE 6.2 SetExpressCheckoutRequest Fields Element
PaymentAction

Description 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 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.
I M P O R T A N T : You cannot set PaymentAction to
Sale on

Data Type
ebl:PaymentAction CodeType xs:token

Allowable Values Default: The transaction resulting from

Required ? No

final sale.
Order Sale

DoExpress Checkout Payment Request will be a
Authorization

SetExpressCheckoutReque st and then change PaymentAction
to Authorization on the final API

DoExpressCheckoutPaymen tRequest.
Character length and limit: Up to 13 single-byte alphabetic characters
BuyerEmail

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
N O T E : The

ebl:EmailAddress Type

See description.

No

AddressType elements are required only if you include the Address element in the SOAP request. fields in the WSDL or XSD files that are not described here are ignored. For example, do not set CountryName.

IMPO RTANT: Any

TABLE 6.3 Address (Shipping Address): AddressType Elements Element
Name

Descriptions Person’s name associated with this shipping address. Character length and limitations: 32 single-byte characters

Data Type
xs:string

Allowable Values See description.

Required? No

Website Payments Pro Integration Guide

July 2006

81

Yes PostalCode xs:string See description. Required? Yes Street2 xs:string See description. Yes Country ebl:CountryCode Type xs:string See Appendix B.Express Checkout API SetExpressCheckout TABLE 6. If you set Token in the SetExpressCheckoutRequest. Character length and limitations: 40 single-byte characters State or province Character length and limitations: 40 single-byte characters U. Character length and limitations: 20 single-byte characters 82 July 2006 Website Payments Pro Integration Guide . Yes SetExpressCheckoutResponse Response to SetExpressCheckoutRequest. Character length and limitations: 100 single-byte characters Second street address.3 Address (Shipping Address): AddressType Elements Element Street1 Descriptions First street address. Data Type xs:string Allowable Values See description.S. No CityName xs:string See description. Character length and limitations: 100 single-byte characters Name of city. Data Type xs:string Value See description. Yes StateOr Province xs:string See description. N O T E : The token expires after three hours. Zip code or other country-specific postal code Character length and limitations: 20 single-byte characters Country code. the value of Token in the response is identical to the value in the request. Fields TABLE 6.4 SetExpressCheckoutResponse Fields Element Token Description A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout. Character limit: Two single-byte characters.

Elements required in the request are indicated with an asterisk.2 GetExpressCheckout Types Website Payments Pro Integration Guide July 2006 83 .Express Checkout API GetExpressCheckoutDetails G e t E x p r e s s C h e c k o u t D e ta i l s GetExpressCheckoutDetails returns information about the customer. including name and address on file with PayPal. Diagram of GetExpressCheckoutDetails Types The following diagram represents the composition of the GetExpressCheckoutDetailsRequestType and GetExpressCheckoutDetailsResponseType elements. FIGURE 6.

5 GetExpressCheckoutDetailsRequest Fields Element Token Description A timestamped token. A free-form field for your own use. PayerInfo ebl:PayerInfoType See Table 6.6 GetExpressCheckoutDetailsResponse Fields Element Token Description The timestamped token value that was returned by SetExpressCheckoutResponse and passed on GetExpressCheckoutDetailsRequest. Character length and limitations: 127 single-byte alphanumeric characters Data Type xs:string Possible Values See the description of “Token” on page 82. See description. as set by you in the Custom element of SetExpressCheckoutRequest. 84 July 2006 Website Payments Pro Integration Guide .Express Checkout API GetExpressCheckoutDetails GetExpressCheckoutDetailsRequest Obtain details about a payment to be processed by PayPal Express Checkout. Character length and limitations: 20 single-byte characters Information about the payer. Character length and limitations: 256 single-byte alphanumeric characters Your own invoice or tracking number. Fields TABLE 6. as set by you in the InvoiceID element of SetExpressCheckoutRequest. Fields TABLE 6. the value of which was returned by SetExpressCheckoutResponse.7 on page 85. Character length and limitations: 20 single-byte characters Data Type xs:string Allowable Values An unexpired token Required ? Yes GetExpressCheckoutDetailsResponse Response to GetExpressCheckoutDetailsRequest. Custom xs:string InvoiceID xs:string See description.

Express Checkout API
GetExpressCheckoutDetails TABLE 6.6 GetExpressCheckoutDetailsResponse Fields Element
ContactPhone

Description Payer’s contact telephone number.
N O T E : PayPal returns a contact telephone number

Data Type
xs:string

Possible Values See description.

only if your Merchant account profile settings require that the buyer enter one. Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers) or +XXX XXXXXXXX (for international numbers)
N O T E : Empty

elements are returned if there is no representative data for the customer. For example, if the customer does not represent a business (and therefore has no business name on file with PayPal), the returned element has no value, like this: <PayerBusiness/>.

NOTE:

TABLE 6.7 Response: PayerInfoType Elements Element
Payer

Description 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. First and last name of payer Payer’s country of residence in the form of ISO standard 3166 two-character country codes. Character length and limitations: Two single-byte characters Payer’s business name. Character length and limitations: 127 single-byte characters Payer's shipping address address information.

DataType
ebl:EmailAddress Type

Possible Values See description.

PayerID

ebl:UserIDType

See description.

PayerStatus

ebl:PayPalUser StatusCodeType

verified unverified
See Table 6.8 on page 86. See Appendix B.

PayerName

ebl:PersonNameType

PayerCountry

ebl:CountryCode Type

PayerBusiness

xs:string

See description.

Address

xs:string

See Table 6.9 on page 86.

.

Website Payments Pro Integration Guide

July 2006

85

Express Checkout API
GetExpressCheckoutDetails

TABLE 6.8 Response: PayerName Elements Element
Salutation

Description Payer’s salutation Character length and limitations: 20 single-byte characters Payer’s first name Character length and limitations: 25 single-byte characters Payer’s middle name Character length and limitations: 25 single-byte characters Payer’s last name Character length and limitations: 25 single-byte characters Payer’s suffix Character length and limitations: 12 single-byte characters Payer’s first name. Character length and limitations: 25 single-byte characters Payer’s last name. Character length and limitations: 25 single-byte characters

DataType
xs:string

Possible Values See description.

FirstName

ebl:PersonNameType

See description.

MiddleName

ebl:NameType

LastName

ebl:NameType

See description.

Suffix

ebl:SuffixType

See description.

FirstName

ebl:NameType

See description.

LastName

ebl:NameType

See description.

TABLE 6.9 Response: AddressType Fields Element
AddressStatus

Descriptions Status of street address on file with PayPal

Data Type ebl:AddressStatus TypeCode
xs:string

Possible Values
none Confirmed Unconfirmed

Name

Person’s name associated with this address. Character length and limitations: 32 single-byte characters First street address. Character length and limitations: 100 single-byte characters

See description.

Street1

xs:string

See description.

86

July 2006

Website Payments Pro Integration Guide

Express Checkout API
DoExpressCheckoutPayment TABLE 6.9 Response: AddressType Fields Element
Street2

Descriptions Second 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 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.

Data Type
xs:string

Possible Values See description.

CityName

xs:string

See description.

StateOr Province

xs:string

See description.

PostalCode

xs:string

See description.

Country

ebl:CountryCode Type xs:string

See Appendix B.

DoExpressCheckoutPayment
With DoExpressCheckoutPayment, you either obtain payment through Express Checkout for a final sale or request authorization for later capture of payment.

Diagram of DoExpressCheckoutPayment Types
The following diagram represents the composition of the DoExpressCheckoutPaymentRequestType and DoExpressCheckoutPaymentResponseType elements. Elements required in the request are indicated with an asterisk.

Website Payments Pro Integration Guide

July 2006

87

Express Checkout API
DoExpressCheckoutPayment FIGURE 6.3 DoExpressCheckoutPayment Types

88

July 2006

Website Payments Pro Integration Guide

Yes Website Payments Pro Integration Guide July 2006 89 . ebl:UserIDType See description. IMPO RTANT: PayPal requires that a merchant using Express Checkout display to the customer the same exact amount that the merchant sends to PayPal in the OrderTotal element with the DoExpressCheckoutPaymentRequest API. Order indicates that this payment is is an order authorization subject to settlement with PayPal Authorization & Capture. 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. Required ? Yes PaymentAction ebl:PaymentAction CodeType xs:token Default: The transaction resulting from No final sale. Character length and limitations: 127 single-byte characters. I M P O R T A N T : You cannot set PaymentAction to Sale on Data Type xs:string Allowable Values See description. Character length and limit: Up to 13 single-byte alphabetic characters PayerID Encrypted PayPal customer account identification number as returned by GetExpressCheckoutDetailsResponse. Order Sale DoExpress Checkout Payment Request will be a Authorization to Authorization on the final PayPal Express Checkout API SetExpressCheckoutReque st and then change PaymentAction DoExpressCheckoutPaymen tRequest.Express Checkout API DoExpressCheckoutPayment DoExpressCheckoutPaymentRequest Request to obtain payment with PayPal Express Checkout. Sale indicates that this is a final sale for which you are requesting payment.10 DoExpressCheckoutPaymentRequest Fields Element Token Description The timestamped token value that was returned by SetExpressCheckoutResponse and passed on GetExpressCheckoutDetailsRequest. Fields TABLE 6.

Required ? Yes one of the three-character currency codes for any of the supported PayPal currencies.000 USD in any currency. Decimal separator must be a period (. handling.). No one of the three-character currency codes for any of the supported PayPal currencies. Character length and limitations: Must not exceed $10. and tax. Equivalent to nine characters maximum for USD. 90 July 2006 Website Payments Pro Integration Guide . and the thousands separator must be a comma (. N O T E : You must set the currencyID attribute to Data Type ebl:BasicAmount Type Allowable Values See description.).). No currency symbol. including shipping. Regardless of currency. Equivalent to nine characters maximum for USD.). and the thousands separator must be a comma (. No currency symbol.11 Request: PaymentDetailsType Fields Element OrderTotal Description Total of order.000 USD in any currency. decimal separator must be a period (.).11 on page 90.Express Checkout API DoExpressCheckoutPayment TABLE 6. No Shipping Total ebl:BasicAmount Type See description. Required ? Yes TABLE 6. Limitations: Must not exceed $10. No currency symbol. N O T E : You must set the currencyID attribute to ebl:BasicAmount Type See description. and the thousands separator must be a comma (. ItemTotal Sum of cost of all items in this order. Regardless of currency.000 USD in any currency. decimal separator must be a period (. Total shipping costs for this order. Character length and limitations: Must not exceed $10.10 DoExpressCheckoutPaymentRequest Fields Element PaymentDetails Description Information about the payment Data Type ebl:PaymentDetails Type Allowable Values See Table 6.).

N O T E : You must set the currencyID attribute to ebl:BasicAmount Type See description.). Character length and limitations: 256 single-byte alphanumeric characters Your own invoice or tracking number. decimal separator must be a period (.Express Checkout API DoExpressCheckoutPayment TABLE 6. Equivalent to nine characters maximum for USD. Character length and limitations: 127 single-byte alphanumeric characters An identification code for use by third-party applications to identify transactions. No one of the three-character currency codes for any of the supported PayPal currencies. No currency symbol. Character length and limitations: Must not exceed $10. Character length and limitations: 32 single-byte alphanumeric characters Your URL for receiving Instant Payment Notification (IPN) about this transaction. Order Description Description of items the customer is purchasing. No Custom xs:string See description. TaxTotal Sum of tax for all items in this order.000 USD in any currency. and the thousands separator must be a comma (.000 USD in any currency. Regardless of currency. Character length and limitations: 2. Character length and limitations: Must not exceed $10. Character length and limitations: 127 single-byte alphanumeric characters A free-form field for your own use. N O T E : If you do not specify NotifyURL in the xs:string See description. the notification URL from your Merchant Profile is used. Required ? No one of the three-character currency codes for any of the supported PayPal currencies.). No request.048 single-byte alphanumeric characters Website Payments Pro Integration Guide July 2006 91 . decimal separator must be a period (. No ButtonSource xs:string See description.11 Request: PaymentDetailsType Fields Element Handling Total Description Total handling costs for this order. Equivalent to nine characters maximum for USD. if one exists.). No NotifyURL xs:string See description. Regardless of currency. N O T E : You must set the currencyID attribute to Data Type ebl:BasicAmount Type Allowable Values See description. No InvoiceID xs:string See description. and the thousands separator must be a comma (.). No currency symbol.

13 on page 93. Details about each individual item included in the order Data Type ebl:AddressType Allowable Values See Table 6. Required ? Yes Street1 xs:string See description.S. do not set CountryName.12 on page 92. For example. Character length and limitations: 40 single-byte characters U. IMPO RTANT: Any TABLE 6. Character limit: Two single-byte characters Data Type xs:string Allowable Values See description.Express Checkout API DoExpressCheckoutPayment TABLE 6. Character length and limitations: 32 single-byte characters First street address. No PostalCode xs:string See description. Character length and limitations: 100 single-byte characters Name of city. Character length and limitations: 20 single-byte characters Country code. No Country ebl:CountryCode Type xs:string See Appendix B. Required ? No No PaymentDetails Item ebl:PaymentDetails ItemType N O T E : The AddressType elements are required only if you include the Address element in the SOAP request. Character length and limitations: 100 single-byte characters Second street address. See Table 6. ZIP code or other country-specific postal code. fields in the WSDL or XSD files that are not described here are ignored. Character length and limitations: 40 single-byte characters State or province.12 Request: ShipToAddress: AddressType Fields Element Name Descriptions Person’s name associated with this address. Yes StateOr Province xs:string See description. Yes 92 July 2006 Website Payments Pro Integration Guide .11 Request: PaymentDetailsType Fields Element ShipToAddress Description Address the order will be shipped to. No CityName xs:string See description. Yes Street2 xs:string See description.

Character length and limitations: 127 single-byte characters Item quantity. decimal separator must be a period (. Character length and limitations: Must not exceed $10.).000 USD in any currency.13 Request: PaymentDetailsItemType Fields Element Name Description Item name. No one of the three-character currency codes for any of the supported PayPal currencies. Website Payments Pro Integration Guide July 2006 93 . N O T E : You must set the currencyID attribute to xs:string See description.000 USD in any currency. Currency code must be set the same as for OrderTotal. and the thousands separator must be a comma (. No one of the three-character currency codes for any of the supported PayPal currencies.).). No Tax ebl:BasicAmount Type See description. DoExpressCheckoutPaymentResponse Response to DoExpressCheckoutPaymentRequest. Equivalent to nine characters maximum for USD. Character length and limitations: Any positive integer Item sales tax. Equivalent to nine characters maximum for USD. Regardless of currency. Number Item number.). No Quantity xs:string See description. Regardless of currency. No currency symbol. decimal separator must be a period (.Express Checkout API DoExpressCheckoutPayment TABLE 6. Character length and limitations: Must not exceed $10. No currency symbol. Required ? No Amount ebl:BasicAmount Type See description. and the thousands separator must be a comma (. Character length and limitations: 127 single-byte characters Cost of item N O T E : You must set the currencyID attribute to Data Type xs:string Allowable Values See description.

Regardless of currency. Character length and limitations:20 single-byte characters Information about the payment.15 Response: PaymentInfoType Elements Element TransactionID Description Unique transaction ID of the payment. Character length and limitations:19 single-byte characters Transaction Type The type of transaction Character length and limitations:15 single-byte characters ns:Payment TransactionCode Type cart express-checkout PaymentType Indicates whether the payment is instant or delayed.Express Checkout API DoExpressCheckoutPayment Fields TABLE 6. Data Type xs:string Possible Values See the description of “Token” on page 82. xs:dateTime none echeck instant Transactionspecific Transactionspecific PaymentDate GrossAmount ebl:BasicAmount Type 94 July 2006 Website Payments Pro Integration Guide . PaymentInfo ebl:PaymentInfo Type See Table 6. and the thousands separator is a comma (. I M P O R T A N T : If the PaymentAction of the request Data Type xs:string Possible Values Transactionspecific was Authorization or Order.000 USD in any currency. including any shipping and taxes from your Merchant Profile. No currency symbol. the value of TransactionID is your AuthorizationID for use with the Authorization & Capture APIs. Character length and limitations: Does not exceed $10. ebl:PaymentCode Character length and limitations: Seven single-byte Type xs:string characters Time/date stamp of payment The final amount charged.15 on page 94. decimal separator is a period (.).).14 DoExpressCheckoutPaymentResponse Fields Element Token Description The timestamped token value that was returned by SetExpressCheckoutResponse and passed on GetExpressCheckoutDetailsRequest. TABLE 6. Equivalent to nine characters maximum for USD.

and the funds have been added successfully to your account balance. Character length and limitations: a decimal that does not exceed 17 characters.).000 USD in any currency. and the thousands separator is a comma (. See the PendingReason element for more information. the conversion occurs in the customer’s account. Equivalent to nine characters maximum for USD.). No currency symbol. Regardless of currency. Tax charged on the transaction. ExchangeRate Exchange rate if a currency conversion occurred. SettleAmount Amount deposited in your PayPal account after a currency conversion.). including decimal point Status of the payment: Completed: The payment has been completed. and the thousands separator is a comma (. decimal separator is a period (. Pending: The payment is pending. ebl:BasicAmount Type Transactionspecific Transactionspecific TaxAmount ebl:BasicAmount Type xs:string Character length and limitations: Does not exceed $10.).Express Checkout API DoExpressCheckoutPayment TABLE 6.15 Response: PaymentInfoType Elements Element FeeAmount Description PayPal fee amount charged for the transaction Data Type ebl:BasicAmount Type Possible Values Transactionspecific Character length and limitations: Does not exceed $10. Regardless of currency. Relevant only if your are billing in their nonprimary currency. decimal separator is a period (. xs:string Transactionspecific PaymentStatus ebl:PaymentStatus CodeType xs:token Completed Pending Website Payments Pro Integration Guide July 2006 95 . Equivalent to nine characters maximum for USD. No currency symbol. If the customer chooses to pay with a currency other than the non-primary currency.000 USD in any currency.

You must verify your account before you can accept this payment. To change your preference. account and do not have a withdrawal mechanism. intl: The payment is pending because you hold a non-U.S. You must manually accept or deny this payment from your Account Overview. contact PayPal customer service. echeck: The payment is pending because it was made by an eCheck that has not yet cleared.15 Response: PaymentInfoType Elements Element PendingReason Description 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. multi-currency: You do not have a balance in the currency sent. other: The payment is pending for a reason other than those listed above. and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. Data Type ebl:PendingStatus CodeType xs:token Possible Values none address echeck intl multi-currency verify other 96 July 2006 Website Payments Pro Integration Guide . verify: The payment is pending because you are not yet verified. You must manually accept or deny this payment. go to the Preferences section of your Profile.Express Checkout API DoExpressCheckoutPayment TABLE 6. For more information.

Elements required in the request are indicated with an asterisk. Diagram of DoDirectPayment Types The following diagram represents the composition of the DoDirectPaymentRequestType and DoDirectPaymentResponseType elements. FIGURE 7. you can obtain payment through PayPal directly from a buyer’s credit card without the buyer logging into PayPal.1 DoDirectPayment Types Website Payments Pro Integration Guide July 2006 97 .7 Direct Payment API With the Direct Payment API.

and expiration date. Character length and limit: Up to 13 single-byte alphabetic characters Data Type ebl:PaymentAction CodeType xs:token Allowable Values Default: The transaction resulting from Required ? No final sale. credit card number.3 on page 100. Fields TABLE 7.Direct Payment API DoDirectPaymentRequest DoDirectPaymentRequest Request to use PayPal Direct Payment to obtain payment. besides the PaymentAction element. Allowable values for the PaymentAction element are Sale or Authorization: Set PaymentAction to Sale if the buyer’s order is final (for example. PaymentDetails 98 July 2006 Website Payments Pro Integration Guide . Sale DoDirect Payment Request will be a Authorization N O T E : Order is not allowed for Direct Payment. In either case.1 DoDirectPaymentRequest Fields Element PaymentAction Description How you want to obtain payment: Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. such as the amount of the transaction. Yes Yes CreditCard Information about the credit card to be charged. type. Sale indicates that this is a final sale for which you are requesting payment. Set PaymentAction to Authorization if the total cost of the order at point of sale is not complete for some reason (such as unknown shipping charges) and you expect to capture funds after checkout is complete. IP address of the buyer’s browser. This transaction is your payment. DoDirectPaymentRequest requires additional elements. and information about both the payer and the payment. You can then use PayPal Authorization & Capture to obtain payment. and you expect no additional charge to the buyer. handling and tax charges). Information about the payment ebl:CreditCard DetailsType ebl:PaymentDetails Type See Table 7. You must include the PaymentAction element in DoDirectPaymentRequest. if the total cost of the order is complete with shipping. See Table 7.2 on page 99.

The currencyId must be GBP. Credit card expiration month Character length and limitations: Two single-byte numeric characters.Direct Payment API DoDirectPaymentRequest TABLE 7. Yes ExpYear xs:int See description. Credit card expiration year Character length and limitations: Four single-byte numeric characters. Required ? Yes to detect possible fraud. xs:string Credit card number Character length and limitations: numeric characters only. Switch. CreditCard Number See important note in description.1 DoDirectPaymentRequest Fields Element IPAddress Description IP address of the payer’s browser as recorded in its HTTP request to your website. Character length and limitations: 15 single-byte characters. Yes Website Payments Pro Integration Guide July 2006 99 . Yes ExpMonth xs:int See description. N O T E : PayPal records this optional session xs:string No identification token as an additional means to detect possible fraud. See description.2 CreditCardDetailsType Fields Element CreditCardType Description Type of credit card. 2. I M P O R T A N T : If the credit card type is Switch or Data Type ebl:CreditCardType Type Allowable Values Visa MasterCard Discover Amex Required ? Yes Solo: 1. Character length and limitations: Up to ten singlebyte alphabetic characters. No spaces or punctutation. See important note in description. N O T E : PayPal records this IP addresses as a means Data Type xs:string Allowable Values Any valid Internet Protocol address. The value of PaymentAction must be Authorization.???. Must conform with modulo and length required by each credit card type.???. including periods. Solo. in dotted-quad format: ???.??? Merchant SessionId Your customer session identification token. including leading zero. Character length and limitations: 64 single-byte numeric characters TABLE 7.

Character length: two-digit. ItemTotal Sum of cost of all items in this order. See note in description. No 100 July 2006 Website Payments Pro Integration Guide . Year that Switch or Solo card was issued. See description.).3 Request: PaymentDetailsType Fields Element OrderTotal Description Data Type ebl:BasicAmount Type Allowable Values Required? Total of order. N O T E : You must include a CVV2 value for those Data Type xs:string Allowable Values See description.Direct Payment API DoDirectPaymentRequest TABLE 7. and Discover cards. Issue number of Switch or Solo card. version 2. Yes No. Required ? No. zero-filled if necessary. N O T E : You must set the currencyID attribute to See description. once a transaction has been completed. Required for Visa. StartMonth xs:int StartYear xs:int IssueNumber xs:int TABLE 7. I M P O R T A N T : To comply with credit card process- ing regulations. See description. and the thousands separator must be a comma (.7 on page 106. MasterCard. Character length and limitations: 127 single-byte characters ebl:BasicAmount Type See description. Other card types might not require a CVV2 value.). ns:PayerInfoType See Table 7. See description. Month that Switch or Solo card was issued. Yes one of the three-character currency codes for any of the supported PayPal currencies. MasterCard.2 CreditCardDetailsType Fields Element CVV2 Description Card Verification Value. Decimal separator must be a period (. American Express. Character length for Visa. No currency symbol. handling. Limitations: Must not exceed $10. Character length: four digits. you must not store the value of CVV2.000 USD in any currency. credit cards that use CVV2. Character length: two numeric digits maximum. No. Character length for American Express: exactly four digits. and tax. including shipping. CardOwner Details about the owner of the credit card. No. and Discover: exactly three digits.

No one of the three-character currency codes for any of the supported PayPal currencies. Decimal separator must be a period (. Decimal separator must be a period (.000 USD in any currency. TaxTotal Sum of tax for all items in this order. Character length and limitations: 32 single-byte alphanumeric characters xs:string See description. and the thousands separator must be a comma (.000 USD in any currency. No currency symbol.). HandlingTotal Total handling costs for this order. N O T E : You must set the currencyID attribute to ebl:BasicAmount Type See description. No ButtonSource xs:string See description. No Custom xs:string See description. Character length and limitations: 127 single-byte alphanumeric characters A free-form field for your own use. N O T E : You must set the currencyID attribute to See description.). Decimal separator must be a period (.). Character length and limitations: 127 single-byte alphanumeric characters An identification code for use by third-party applications to identify transactions. No InvoiceID xs:string See description. No currency symbol. Limitations: Must not exceed $10. No one of the three-character currency codes for any of the supported PayPal currencies.).). Character length and limitations: 256 single-byte alphanumeric characters Your own invoice or tracking number. Limitations: Must not exceed $10. No currency symbol.). Order Description Description of items the customer is purchasing. and the thousands separator must be a comma (. No Website Payments Pro Integration Guide July 2006 101 .000 USD in any currency. as set by you in the InvoiceID element of SetExpressCheckoutRequest. N O T E : You must set the currencyID attribute to ebl:BasicAmount Type See description. and the thousands separator must be a comma (. No one of the three-character currency codes for any of the supported PayPal currencies.3 Request: PaymentDetailsType Fields Element ShippingTotal Description Data Type ebl:BasicAmount Type Allowable Values Required? Total shipping costs for this order.Direct Payment API DoDirectPaymentRequest TABLE 7. Limitations: Must not exceed $10.

Character length and limitations: 100 single-byte characters Second street address. No PostalCode xs:string No 102 July 2006 Website Payments Pro Integration Guide .3 Request: PaymentDetailsType Fields Element NotifyURL Description Data Type xs:string Allowable Values Required? Your URL for receiving Instant Payment Notification (IPN) about this transaction. ZIP code or other country-specific postal code.Direct Payment API DoDirectPaymentRequest TABLE 7. See Table 7. the notification URL from your Merchant Profile is used. Character length and limitations: 100 single-byte characters Name of city. Required ? Yes Street1 xs:string See description.4 on page 102. No CityName xs:string See description.4 Request: ShipToAddress: AddressType Fields Element Name Descriptions Person’s name associated with this address. Character length and limitations: 2.048 single-byte alphanumeric characters ShipToAddress Address the order will be shipped to. Character length and limitations: 40 single-byte characters U. No request. do not set CountryName. Character length and limitations: 20 single-byte characters Data Type xs:string Allowable Values See description. Yes StateOr Province xs:string See Table 7. Character length and limitations: 32 single-byte characters First street address. Details about each individual item included in the order ebl:AddressType See Table 7. N O T E : If you do not specify NotifyURL in the See description. Yes Street2 xs:string See description. No No PaymentDetails Item ebl:PaymentDetails ItemType IMPO RTANT: Any fields in the WSDL or XSD files that are not described here are ignored. if one exists. For example.6 on page 106.S. Character length and limitations: 40 single-byte characters State or province.5 on page 103 See description. TABLE 7.

State Alberta British Columbia Manitoba New Brunswick Newfoundland and Labrador Northwest_Territories Nova_Scotia Nunavut Ontario Prince_Edward_Island Quebec Saskatchewan Yukon Alabama Alaska American_Samoa Arizona Arkansas California Colorado Connecticut Delaware AB BC MB NB NF NT NS NU ON PE QC SK YK AL AK AS AZ AR CA CO CT DE Website Payments Pro Integration Guide July 2006 103 .5 StateOrProvince: Abbreviations for Canada and U. Canadian Province or U. Required ? Yes TABLE 7.Direct Payment API DoDirectPaymentRequest TABLE 7.S.4 Request: ShipToAddress: AddressType Fields Element Country Descriptions Country code. Character limit: Two single-byte characters Data Type ebl:CountryCode Type xs:string Allowable Values See Appendix B.S.

S.Direct Payment API DoDirectPaymentRequest TABLE 7. Canadian Province or U.S.5 StateOrProvince: Abbreviations for Canada and U. State District Of Columbia Federated States Of Micronesia Florida Georgia Guam Hawaii Idaho Illinois Indiana Iowa Kansas Kentucky Louisiana Maine Marshall_Islands Maryland Massachusetts Michigan Minnesota Mississippi Missouri Montana Nebraska Nevada New Hampshire New Jersey New Mexico New York DC FM FL GA GU HI ID IL IN IA KS KY LA ME MH MD MA MI MN MS MO MT NE NV NH NJ NM NY 104 July 2006 Website Payments Pro Integration Guide .

Canadian Province or U.Direct Payment API DoDirectPaymentRequest TABLE 7.S.5 StateOrProvince: Abbreviations for Canada and U.S. State North Carolina North Dakota Northern Mariana Islands Ohio Oklahoma Oregon Palau Pennsylvania Puerto Rico Rhode Island South Carolina South Dakota Tennessee Texas Utah Vermont Virgin_Islands Virginia Washington West_Virginia Wisconsin Wyoming Armed_Forces_Americas Armed_Forces Armed_Forces_Pacific NC ND MP OH OK OR PW PA PR RI SC SD TN TX UT VT VI VA WA WV WI WY AA AE AP Website Payments Pro Integration Guide July 2006 105 .

Character length and limitations: any valid currency amount.Direct Payment API DoDirectPaymentRequest TABLE 7. No one of the three-character currency codes for any of the supported PayPal currencies. Decimal separator must be a period (. Character length and limitations: Any positive integer Item sales tax.000 USD in any currency.). currency code is set the same as for OrderTotal. Number Item number. Yes LastName ns:PersonName Type See description. Character length and limitations: 127 single-byte characters Cost of item N O T E : You must set the currencyID attribute to Data Type xs:string Allowable Values See description. Character length and limitations: 127 single-byte characters Item quantity. Yes 106 July 2006 Website Payments Pro Integration Guide . No Quantity xs:string See description. Limitations: Must not exceed $10. Character length and limitations: 25 single-byte characters DataType ns:EmailAddress Type Allowable Values See description. No currency symbol. No Tax ebl:BasicAmount Type See description. and the thousands separator must be a comma (. Character length and limitations: 25 single-byte characters Payer’s last name.6 Request: PaymentDetailsItemType Fields Element Name Description Item name. No TABLE 7. Required ? No Amount ebl:BasicAmount Type See description. Required ? No FirstName ns:PersonName Type See description.7 CardOwner: PayerInfoType Fields Element Payer Description Email address of payer. xs:string See description.). Character length and limitations: 127 single-byte characters Payer’s first name.

U.Direct Payment API DoDirectPaymentRequest TABLE 7.8 on page 107. Yes StateOr Province xs:string See description. Character length and limitations: Two single-byte characters. Required ? Yes Street2 xs:string See description. No CityName xs:string See description. Yes Country ebl:CountryCode Type xs:string xs:string See Appendix 1. Required ? Yes TABLE 7.7 CardOwner: PayerInfoType Fields Element Address Description Payer’s billing address information DataType ns:AddressType Allowable Values See Table 7.8 CardOwner: AddressType Fields Element Street1 Description First street address Character length and limitations: 100 single-byte characters Second 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. Yes Website Payments Pro Integration Guide July 2006 107 . Yes PostalCode See description.S. Zip code or other country-specific postal code Character length and limitations: 20 single-byte characters DataType xs:string Allowable Values See description.

10. TransactionID is your record of the transaction processed with PayPal. AVSCode “AVS Response Codes” on page 109.9 DoDirectPaymentResponse Fields Element TransactionID Description Unique transaction ID of the payment. the value of TransactionID is your AuthorizationID for use with the Authorization & Capture APIs. Fields TABLE 7. DoDirectPaymentResponse also returns the result of checking the buyer’s postal address and credit card number (as submitted by you with DoDirectPaymentRequest) against the U. The Direct Payment API response contains the TransactionID element.11. In the case of a final Sale. was Authorization. 108 July 2006 Website Payments Pro Integration Guide . CVV2Code xs:string See Table 7.S. “CVV2 Response Codes” on page 109. In the case of an Authorization. Address Verification System response code. I M P O R T A N T : If the PaymentAction of the request Data Type xs:string Possible Values See description. banking industry standard Address Verification System (AVS) and Credit Card Verification (CVV2) system. See Table 7. ebl:BasicAmount Type xs:string See description. TransactionID is your key to capturing funds with PayPal Authorization & Capture. Character limit: One single-byte alphanumeric character Result of the CVV2 check by PayPal. Character length and limitations: 19 single-byte characters Amount The amount of the payment as specified by you on DoDirectPaymentRequest.Direct Payment API DoDirectPaymentResponse DoDirectPaymentResponse Response to DoDirectPaymentRequest.

10 AVS Response Codes AVS Code A B C D E F G I N P R S U W X Y Z All others Meaning Address International “A” International “N” International “X” 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 Matched Details Address only (no ZIP) Address only (no ZIP) None Address and Postal Code Not applicable Address and Postal Code Not applicable Not applicable None Postal Code only (no Address) Not applicable Not applicable Not applicable Nine-digit ZIP code (no Address) Address and nine-digit ZIP code Address and five-digit ZIP Five-digit ZIP code (no Address) Not applicable TABLE 7.11 CVV2 Response Codes CVV2 Code M N Meaning Match No match Matched Details CVV2 None Website Payments Pro Integration Guide July 2006 109 .Direct Payment API DoDirectPaymentResponse TABLE 7.

Direct Payment API DoDirectPaymentResponse TABLE 7.11 CVV2 Response Codes CVV2 Code P S U X All others Meaning Not Processed Service not Supported Unavailable No response Error Matched Details Not applicable Not applicable Not applicable Not applicable Not applicable 110 July 2006 Website Payments Pro Integration Guide .

TABLE 8. DoAuthorization 3. DoCapture 2. and Types of Authorization Purpose Settle an order or previously authorized transaction and obtain payment for either the complete amount or any portion of it. DoReauthorization Order only Order and Basic Basic only Funds Availability Both DoAuthorization and DoReauthorization check the availability of a PayPal member’s funds to obtain another honor period or to make a payment higher than you originally authorized.8 API Authorization & Capture API The Authorization & Capture API consists of individual requests and responses. Void an original authorization or order Reauthorize a previously authorized transaction Used With Type of Authorization Order and Basic 1.1 Authorization & Capture API Names. Website Payments Pro Integration Guide June 2006 111 . as shown below. Purposes. DoVoid 4. up to 115% of the originally authorized amount (not to exceed an increase of $75 USD). Authorize an order that can be fulfilled over 29 days.

or reauthorization. Elements required in the request are marked with an asterisk. N O T E : DoCaptureRequest is for use with both basic and order authorizations. Diagram of DoCapture Types The following diagram represents the composition of the DoCaptureRequestType and DoCaptureResponseType elements. an authorization. FIGURE 8.1 DoCapture Types 112 June 2006 Website Payments Pro Integration Guide .Authorization & Capture API DoCapture DoCapture DoCaptureRequest is your request to completely or partially settle an order.

not a basic authorization.).000 USD in any currency. This can be an order number. N O T E : The InvoiceID value is recorded only if the xs:string See description. The default is Complete. No Website Payments Pro Integration Guide June 2006 113 . or a rauthorization number. Fields TABLE 8. Yes CompleteType ebl:Complete CodeType Default: Yes Complete NotComplete amount of the original reauthorized transaction is automatically voided. any remaining See description. Limitations: Must not exceed $10. Character length and limits: 255 single-byte characters xs:string See description. 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. an order authorization number. Character length and limits: 19 single-byte characters maximum Amount to capture. No currency symbol.). Indicates if this capture is the last capture you intend to make. No authorization you are capturing is an order authorization.Authorization & Capture API DoCapture DoCaptureRequest Request to capture funds from a PayPal member’s account. Yes Amount ebl:BasicAmount Type See description.2 DoCaptureRequest Fields Element Authorization ID Description Data Type xs:string Allowable Values Required? The authorization identification number of the payment you want to capture. N O T E : If CompleteType is Complete. Character length and limits: 12 single-byte alphanumeric characters InvoiceID Your invoice number or other identification number. and the thousands separator must be a comma (. Decimal separator must be a period (.

See description.4 on page 114. Character length and limitations: 17 single-byte characters The type of transaction Character length and limitations: 15 single-byte characters Transactionspecific cart express-checkout Transaction Type ns:Payment TransactionCode Type PaymentType Indicates whether the payment is instant or delayed.Authorization & Capture API DoCapture DoCaptureResponse Response to DoCaptureRequest. ebl:PaymentCode Character length and limitations: Seven single-byte Type xs:string characters Time/date stamp of payment The final amount charged. PaymentInfo ebl:PaymentInfo Type See Table 8. ebl:BasicAmountTyp e 114 June 2006 Website Payments Pro Integration Guide .4 Response: PaymentInfoType Elements Element TransactionID Description Data Type xs:string Possible Values Unique transaction ID of the payment. including any shipping and taxes form your Merchant Profile. TABLE 8.3 DoCaptureResponse Fields Element Authorization ID Description Data Type xs:string Possible Values The authorization identification number you specified in the request. Character length and limits: 19 single-byte characters maximum Information about the payment. Fields TABLE 8. PayPal fee amount charged for the transaction xs:dateTime none echeck instant PaymentDate Transactionspecific Transactionspecific Transactionspecific Transactionspecific GrossAmount ebl:BasicAmountTyp e FeeAmount ebl:BasicAmountTyp e SettleAmount Amount deposited in your PayPal account after a currency conversion.

This happens only if the payment was made from your customer’s bank account. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element. the conversion occurs in the customer’s account. For example. and the funds have been added successfully to your account balance. Processed: A payment has been accepted. The funds have been removed from your account balance and returned to the buyer. The status of the payment: None: No status Canceled-Reversal: This means a reversal has been canceled. See the PendingReason element for more information. Character length and limitations: a decimal multiplier Status of the payment. Completed: The payment has been completed. Relevant only if you are billing in the customer’s non-primary currency. xs:string Transactionspecific PaymentStatus ebl:PaymentStatus CodeType xs:token None Canceled-Reversal Completed Denied Expired Failed Pending Refunded Reversed Processed Voided Website Payments Pro Integration Guide June 2006 115 . Reversed: A payment was reversed due to a chargeback or other type of reversal. Expired: the authorization period for this payment has been reached. Refunded: You refunded the payment. you won a dispute with the customer. Denied: You denied the payment. Failed: The payment has failed. The reason for the reversal is specified in the ReasonCode element. Voided: An authorization for this transaction has been voided. and the funds for the transaction that was reversed have been returned to you. Pending: The payment is pending.Authorization & Capture API DoCapture TABLE 8.4 Response: PaymentInfoType Elements Element TaxAmount Description Data Type ebl:BasicAmount Type xs:string Possible Values Tax charged on the transaction Transactionspecific ExchangeRate Exchange rate if a currency conversion occurred. If the customer chooses to pay with a currency other than the non-primary currency.

verify: The payment is pending because you are not yet verified. and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. contact PayPal Customer Service. To change your preference.Authorization & Capture API DoCapture TABLE 8. intl: The payment is pending because you hold a non-U. 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. echeck: The payment is pending because it was made by an eCheck that has not yet cleared. 116 June 2006 Website Payments Pro Integration Guide .4 Response: PaymentInfoType Elements Element PendingReason Description Data Type ebl:PendingStatus CodeType xs:token Possible Values none address echeck intl multi-currency verify other N O T E : PendingReason is returned in the response only if PaymentStatus is Pending. account and do not have a withdrawal mechanism.S. multi-currency: You do not have a balance in the currency sent. You must manually accept or deny this payment. go to the Preferences section of your Profile. other: The payment is pending for a reason other than those listed above. For more information. You must verify your account before you can accept this payment. You must manually accept or deny this payment from your Account Overview.

2 DoAuthorization Types Website Payments Pro Integration Guide June 2006 117 . After you ship. not basic authorizations. you can capture funds with DoCapture. With a shopping cart or PayPal Website Payments transaction with the paymentaction HTML variable set to order. Elements required in the request are marked with an asterisk. To use DoAuthorization you must have previously created a customer order. Diagram of DoAuthorization Types The following diagram represents the composition of the DoAuthorizationRequestType and DoAuthorizationResponseType elements. N O T E : DoAuthorizationRequest is for use only with order authorizations. You can create an order in several ways: With the DoExpressCheckoutPaymentRequest or DoDirectPaymentRequest PaymentAction element set to Order. FIGURE 8. You use DoAuthorizationRequest when you are ready to ship goods to your customer.Authorization & Capture API DoAuthorization DoAuthorization DoAuthorizationRequest is your request to authorize a customer order that can be fulfilled within 29 days.

Decimal separator must be a period (. 118 June 2006 Website Payments Pro Integration Guide . Fields TABLE 8. Type of transaction to authorize.). Character length and limits: 17 single-byte characters The amount you specified in the request. The only allowable value is Order. See description. Limitations: Must not exceed $10. Yes Amount ebl:BasicAmount Type See description. Character length and limits: 19 single-byte characters maximum Amount to authorize.000 USD in any currency. which means that the transaction represents a customer order that can be fulfilled over 29 days. Yes TransactionEnt ity ebl:Transaction EntityType Order No DoAuthorizationResponse Response to DoAuthorizationRequest.). Amount ebl:BasicAmount Type See description. No currency symbol.5 DoAuthorizationRequest Fields Element TransactionID Description Data Type xs:string Allowable Values Required? The value of the order’s transaction identification number returned by a PayPal product. Fields TABLE 8.Authorization & Capture API DoAuthorization DoAuthorizationRequest Request to authorize all or part of a customer order amount. and the thousands separator must be a comma (.6 DoAuthorizationResponse Fields Element TransactionID Description Data Type xs:string Possible Values An authorization identification number. See description.

the authorization or reauthorization of a transaction is implicitly voided. Diagram of DoVoid Types The following diagram represents the composition of the DoVoidRequestType and DoVoidResponseType elements. IMPO RTANT: The AuthorizationID value on DoVoidRequest must be the original authorization identification number. By definition. FIGURE 8.Authorization & Capture API DoVoid D o Vo i d DoVoidRequest voids an order or an authorization.3 DoVoid Types Website Payments Pro Integration Guide June 2006 119 . when the authorization period expires. N O T E : DoVoidRequest is for use with both basic and order authorizations. Elements required in the request are marked with an asterisk. not the value of AuthorizationID returned by DoReauthorizationResponse.

No DoVoidResponse Response to DoVoidRequest. use the ID from the original authorization. Fields TABLE 8. Character length and limits: 19 single-byte characters Note An informational note about this settlement that is displayed to the payer in email and in his transaction history. and not the reauthorization. Fields TABLE 8. Character length and limits: 19 single-byte characters See description. I M P O R T A N T : If you are voiding a transaction that See description.7 DoVoidRequest Fields Element AuthorizationI D Description Data Type xs:string Allowable Values Required? The value of the original authorization identification number returned by a PayPal product. Yes has been reauthorized. Character length and limits: 255 single-byte characters xs:string See description.8 DoVoidResponse Fields Element Authorization ID Description Data Type xs:string Possible Values The authorization identification number you specified in the request. 120 June 2006 Website Payments Pro Integration Guide .Authorization & Capture API DoVoid DoVoidRequest Request to void a prior authorization.

4 DoReauthorization Types Website Payments Pro Integration Guide June 2006 121 . When DoReauthorizationResponse returns success. – With the DoExpressCheckoutPaymentRequest PaymentAction element set to Authorization. you can capture funds. not order authorizations. Elements required in the request are marked with an asterisk. You can authorize a transaction in several ways: – From the Merchant Services tab of your PayPal merchant account. FIGURE 8. N O T E : DoReauthorizationRequest is for use only with basic authorizations. You can invoke DoReauthorizationRequest as many times as necessary to obtain one successful reauthorization. – With a shopping cart transaction (such as one that uses PayPal Website Payments) with the paymentaction HTML variable set to authorization.Authorization & Capture API DoReauthorization DoReauthorization To use DoReauthorization you must have previously authorized a transaction. but you can no longer reauthorize. Diagram of DoReauthorization Types The following diagram represents the composition of the DoReauthorizationRequestType and DoReauthorizationResponseType elements. the settlement period restarts.

cc:BasicAmount Type See description. N O T E : You can obtain a buyer’s transaction number from the TransactionID element of the PayerInfo structure returned by Any previously authorized PayPal transaction identification number. Yes DoReauthorizationResponse Response to DoReauthorizationRequest. Character length and limits: 19 single-byte characters Data Type xs:string Possible Values See description.10 DoReauthorizationResponse Fields Element Authorization ID Description A new authorization identification number. Fields TABLE 8.000 USD in any currency. Fields TABLE 8. Limitations: Must not exceed $10. No currency symbol.).). and the thousands separator must be a comma (.Authorization & Capture API DoReauthorization DoReauthorizationRequest Request to use Authorization & Capture to reauthorize a transaction. Character length and limits: 19 single-byte characters maximum Amount Amount to reauthorize. Decimal separator must be a period (.9 DoReauthorizationRequest Fields Element Authorization ID Description Data Type xs:string Allowable Values Required? The value of a previously authorized transaction identification number returned by a PayPal product. 122 June 2006 Website Payments Pro Integration Guide . Yes GetTransactionDetailsRespons e.

A Error Code 10001 10001 10001 Short Message Express Checkout API Error Codes. See additional error messages for details. Please try later or use other PaymentAction. and Long Messages Express Checkout API Errors TABLE A. Internal Error Internal Error ButtonSource value truncated... See additional error messages for details. See additional error messages for details. Short Message. Transaction refused because of an invalid argument. Internal Error Transaction refused because of an invalid argument. Website Payments Pro Integration Guide July 2006 123 .1 SetExpressCheckout API Errors Long Message Internal Error Transaction failed due to internal error The transaction could not be loaded Internal Error Transaction refused because of an invalid argument. Correcting This Error. Permission denied PaymentActio n of Order Temporarily Unavailable 10001 10004 10004 The transaction id is not valid 10007 10102 You do not have permissions to make this API call PaymentAction of Order is temporarily unavailable.

. 10404 10405 CancelURL is missing. 10410 124 July 2006 Website Payments Pro Integration Guide .. Short Message. 10409 Express Checkout token was issued for a merchant account other than yours. Invalid token. Please contact Customer Service. 10407 Invalid buyer email address (BuyerEmail).1 SetExpressCheckout API Errors Error Code 10402 Short Message Authorization only is not allowed for merchant. and Long Messages Express Checkout API Errors TABLE A. See additional error messages for details. ReturnURL is missing. See additional error messages for details. Correcting This Error. Transaction refused because of an invalid argument.Express Checkout API Error Codes. Transaction refused because of an invalid argument. See additional error messages for details. You're not authorized to access this info. Transaction refused because of an invalid argument. Invalid token Long Message This merchant account is not permitted to set PaymentAction to Authorization.

Please contact Customer Service. Website Payments Pro Integration Guide July 2006 125 . Handling this error If you determine that your customers are clicking your “Place Order” button twice. If you get this error. and provide a button to return to PayPal. Express Checkout has been disabled for this merchant. The token returned by SetExpressCheckoutResponse expires after three hours. In this situation. you must return your customer to PayPal to approve the use of PayPal again. Long Message This Express Checkout session has expired. If you attempt to send the DoExpressCheckoutPaymentRequest after that time. you will receive error code 10411 in DoExpressCheckoutPaymentResponse. 10412 Duplicate invoice Payment has already been made for this InvoiceID. PayPal recommends that you disable the button after your customer has clicked it. if necessary.. Correcting This Error. be sure to update the value for that element if appropriate. Short Message. you are effectively restarting the entire checkout process. PayPal returns error code 10412. PayPal allows a token only once for a successful transaction. If you receive this error. A successful transaction has already been completed for this token.. 10425 Express Checkout has been disabled for this merchant. research why might occur and modify your implementation of Express Checkout to ensure that you generate unique invoice identification numbers. because you already know the final OrderTotal. and Long Messages Express Checkout API Errors TABLE A. You might also want to update the values for ReturnURL and CancelURL. Token value is no longer valid. You might not be able to correct this error during an actual checkout. 10415 Transaction refused because of an invalid argument. If you send an InvoiceID value already associated with another transaction in the PayPal system. PayPal checks that InvoiceID values are unique for any particular merchant. (Do not reuse the expired token value on SetExpressCheckoutRequest. See additional error messages for details.) However.1 SetExpressCheckout API Errors Error Code 10411 Short Message This Express Checkout session has expired.Express Checkout API Error Codes. Display an error message to inform the customer that the transaction expired.

Transaction refused because of an invalid argument. Transaction refused because of an invalid argument. See additional error messages for details. 10434 Value of Custom element has been truncated. Long Message Invoice ID value exceeds maximum allowable length. 10433 Value of OrderDescription element has been truncated.1 SetExpressCheckout API Errors Error Code 10432 Short Message Transaction refused because of an invalid argument. 10437 cpp-header-image value exceeds maximum allowable length. Transaction refused because of an invalid argument. See additional error messages for details... 126 July 2006 Website Payments Pro Integration Guide .Express Checkout API Error Codes. See additional error messages for details. Short Message. Transaction refused because of an invalid argument. See additional error messages for details. Correcting This Error. and Long Messages Express Checkout API Errors TABLE A. See additional error messages for details. 10436 PageStyle value exceeds maximum allowable length.

Payment declined by your Risk Controls settings: PayPal Risk Model. See additional error messages for details. Transaction refused because of an invalid argument. 10538 Risk Control Max Amount Failure 10539 Payment declined by your Risk Controls settings: PayPal Risk Model. See additional error messages for details. Website Payments Pro Integration Guide July 2006 127 .1 SetExpressCheckout API Errors Error Code 10438 Short Message Transaction refused because of an invalid argument. Short Message. and Long Messages Express Checkout API Errors TABLE A. Risk Control Country Filter Failure Long Message cpp-header-image value exceeds maximum allowable length. 10440 cpp-header-image value exceeds maximum allowable length. See additional error messages for details. The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk Control Settings. 10537 The transaction was refused because the country was prohibited as a result of your Country Monitor Risk Control Settings.. 10439 cpp-header-image value exceeds maximum allowable length. Correcting This Error. Transaction refused because of an invalid argument..Express Checkout API Error Codes.

.2 GetExpressCheckoutDetails API Errors Error Code 10001 10001 10001 Short Message Internal Error Internal Error ButtonSource value truncated. and Postal Code failed.. 10001 128 July 2006 Website Payments Pro Integration Guide .. ButtonSource value truncated.Express Checkout API Error Codes. State. and Long Messages Express Checkout API Errors TABLE A.1 SetExpressCheckout API Errors Error Code 10725 Short Message Shipping Address Country Error Shipping Address1 Empty Shipping Address City Empty Shipping Address State Empty Shipping Address Postal Code Empty Shipping Address Country Empty Shipping Address Invalid City State Postal Code Long Message 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. Short Message. Long Message Internal Error Transaction failed due to internal error The transaction could not be loaded The transaction could not be loaded Correcting This Error.. Correcting This Error. 10727 10728 10729 10730 10731 10736 TABLE A.

Transaction refused because of an invalid argument. Transaction refused because of an invalid argument. 10004 The transaction id is not valid 10004 You can not get the details for this type of transaction The transaction could not be loaded 10004 10004 The transaction id is not valid 10007 10007 10007 You do not have permissions to make this API call You do not have permission to get the details of this transaction You do not have permissions to make this API call Website Payments Pro Integration Guide July 2006 129 . Permission denied Permission denied Permission denied Long Message Transaction refused because of an invalid argument. See additional error messages for details. and Long Messages Express Checkout API Errors TABLE A. See additional error messages for details.. Invalid transaction type Transaction refused because of an invalid argument. See additional error messages for details. See additional error messages for details. Correcting This Error. Short Message..2 GetExpressCheckoutDetails API Errors Error Code 10004 Short Message Transaction refused because of an invalid argument.Express Checkout API Error Codes. See additional error messages for details.

Internal Error Transaction refused because of an invalid argument..Express Checkout API Error Codes.. You're not authorized to access this info. See additional error messages for details. 10001 10004 130 July 2006 Website Payments Pro Integration Guide . 10001 ButtonSource value truncated.3 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 Transaction refused because of an invalid argument. Correcting This Error. Long Message Express Checkout token is missing.. Invalid token.2 GetExpressCheckoutDetails API Errors Error Code 10408 Short Message Express Checkout token is missing. 10409 Express Checkout token was issued for a merchant account other than yours. Correcting This Error. 10410 10411 TABLE A.. Invalid token This Express Checkout session has expired. Short Message. This Express Checkout session has expired. Token value is no longer valid. See additional error messages for details. and Long Messages Express Checkout API Errors TABLE A.

You're not authorized to access this info. 10408 Express Checkout token is missing. This Express Checkout session has expired. and Long Messages Express Checkout API Errors TABLE A. Invalid token. 10409 Express Checkout token was issued for a merchant account other than yours. Payment has already been made for this InvoiceID. See additional error messages for details. Express Checkout token is missing.3 DoExpressCheckoutPayment API Errors Error Code 10004 Short Message Transaction refused because of an invalid argument. Permission denied Transaction refused because of an invalid argument.Express Checkout API Error Codes. See additional error messages for details.. Token value is no longer valid.. Invalid token This Express Checkout session has expired. Short Message. 10410 10411 10412 Website Payments Pro Integration Guide July 2006 131 . 10007 10406 You do not have permissions to make this API call The PayerID value is invalid. Duplicate invoice Long Message The transaction id is not valid Correcting This Error.

You can send a maximum of 10 DoExpressCheckoutPayment API calls for any single token value. 132 July 2006 Website Payments Pro Integration Guide .3 DoExpressCheckoutPayment API Errors Error Code 10413 Short Message Transaction refused because of an invalid argument.Express Checkout API Error Codes.. See additional error messages for details. If you include any of the following element values with DoExpressCheckoutPayment. See additional error messages for details. Short Message. and Long Messages Express Checkout API Errors TABLE A. research why it might have occurred and modify your implementation of Express Checkout to ensure proper addition of the values. The amount exceeds the maximum amount for a single transaction. 10416 You have exceeded the maximum number of payment attempts for this token. the sum of their values must equal the value of OrderTotal. Correcting This Error. ItemTotal ShippingTotal HandlingTotal TaxTotal If you get this error.. Transaction refused because of an invalid argument. See additional error messages for details. after which the token becomes invalid. Long Message The totals of the cart item amounts do not match order amounts. 10415 A successful transaction has already been completed for this token. Transaction refused because of an invalid argument. 10414 Transaction refused because of an invalid argument. See additional error messages for details.

returns error code 10417. Express Checkout PayerID is missing. Another possible. 10420 Express Checkout PaymentAction is missing. See additional error messages for details. 10418 Transaction refused because of an invalid argument. Short Message. Website Payments Pro Integration Guide July 2006 133 . and Long Messages Express Checkout API Errors TABLE A.. cause is that the final OrderTotal is significantly higher than the original estimated OrderTotal you sent with SetExpressCheckout at Integration Point 1. The currencies of the shopping cart amounts must be the same. If the customer has no other PayPal funding source that is likely to succeed. See additional error messages for details. Correcting This Error. though rare. It is possible that the payment method the customer chooses on PayPal might not succeed when you send DoExpressCheckoutPayment.. The most likely cause is that the customer’s credit card failed bank authorization. Instruct the customer that PayPal is unable to process the payment and redisplay alternative payment methods with which the customer can pay. DoExpressCheckoutPaymentResponse 10419 Express Checkout PayerID is missing. Transaction refused because of an invalid argument.3 DoExpressCheckoutPayment API Errors Error Code 10417 Short Message Transaction cannot complete. Long Message The transaction cannot complete successfully.Express Checkout API Error Codes. Instruct the customer to use an alternative payment method. and the final OrderTotal does not pass PayPal’s risk model analysis.

the chapter about best practices in 10424 Transaction refused because of an invalid argument. When your customer logs into PayPal. If the customer has a different PayPal funding source that is likely to succeed. Shipping address is invalid. PayPal recommends that you return your customer to PayPal to review and approve new valid funding sources. Long Message This Express Checkout session belongs to a different customer. The Token and PayerID returned for any particular customer by must be the same ones you send with DoExpressCheckoutPayment.3 DoExpressCheckoutPayment API Errors Error Code 10421 Short Message This Express Checkout session belongs to a different customer. Item amount is invalid. you should consider trapping the error to display a message to the customer describing what happened.. See additional error messages for details. Verify that your programs are properly associating the Tokens and PayerIDs. Token value mismatch.Express Checkout API Error Codes. GetExpressCheckoutDetailsResponse DoExpressCheckoutPaymentResponse This error occurs if at Integration Point 1. you set PaymentAction to Sale with SetExpressCheckoutRequest but at Integration Point 3. The customer must return to PayPal to select new funding sources. This transaction cannot be completed with PaymentAction of Authorization. If you receive this error message. returns error code 10422 so you can redirect the customer back to PayPal. See additional error messages for details. PayPal does not allow this switch from Sale to Authorization in a single checkout session.. 10431 Item amount is invalid. Correcting This Error. 10423 Transaction refused because of an invalid argument. and Long Messages Express Checkout API Errors TABLE A. Short Message. It is possible that the payment method the customer chooses on PayPal might not succeed when you send DoExpressCheckoutPaymentRequest. 10422 Customer must choose new funding sources. 134 July 2006 Website Payments Pro Integration Guide . Although this error is rare. along with a button or hyperlink to return to PayPal. This error is caused by mixing tokens for two different PayerIDs. however. You can set PaymentAction to Authorization with SetExpressCheckout at Integration Point 1 and switch PaymentAction to Sale with DoExpressCheckoutPayment at Integration Point 3. you set PaymentAction to Authorization with DoExpressCheckoutPayment. the PayPal PayerID is associated with the Express Checkout token. PayPal does allow the reverse.

Transaction refused because of an invalid argument. and Long Messages Express Checkout API Errors TABLE A. See additional error messages for details. Correcting This Error. 10441 The NotifyURL element value exceeds maximum allowable length. Website Payments Pro Integration Guide July 2006 135 . See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. See additional error messages for details.. ButtonSource value truncated.Express Checkout API Error Codes. Long Message Invoice ID value exceeds maximum allowable length.3 DoExpressCheckoutPayment API Errors Error Code 10432 Short Message Transaction refused because of an invalid argument. Transaction refused because of an invalid argument. 10433 Value of OrderDescription element has been truncated. See additional error messages for details.. 10434 Value of Custom element has been truncated. Transaction refused because of an invalid argument. 10435 The customer has not yet confirmed payment for this Express Checkout session. Short Message. 10442 The ButtonSource element value exceeds maximum allowable length.

Correcting This Error. 136 July 2006 Website Payments Pro Integration Guide . The transaction was refused because the country was prohibited as a result of your Country Monitor Risk Control Settings. Payment declined by your Risk Controls settings: PayPal Risk Model. Transaction refused because of an invalid argument. The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk Control Settings. 10538 Risk Control Max Amount Failure 10539 Payment declined by your Risk Controls settings: PayPal Risk Model. Unconfirmed email Risk Control Country Filter Failure Long Message This transaction cannot be completed with PaymentAction of Order. 10446 10537 A confirmed email is required to make this API call. See additional error messages for details. Short Message.3 DoExpressCheckoutPayment API Errors Error Code 10443 Short Message Transaction refused because of an invalid argument. and Long Messages Express Checkout API Errors TABLE A. Please try again later. 10444 The transaction currency specified must be the same as previously specified.Express Checkout API Error Codes.. This transaction cannot be processed at this time. 10445 This transaction cannot be processed at this time. See additional error messages for details.. Please try again later.

State. Short Message. and Long Messages Express Checkout API Errors TABLE A. 10727 10728 10729 10730 10731 10736 Website Payments Pro Integration Guide July 2006 137 . and Postal Code failed.Express Checkout API Error Codes...3 DoExpressCheckoutPayment API Errors Error Code 10725 Short Message Shipping Address Country Error Shipping Address1 Empty Shipping Address City Empty Shipping Address State Empty Shipping Address Postal Code Empty Shipping Address Country Empty Shipping Address Invalid City State Postal Code Long Message 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. Correcting This Error.

and Long Messages Express Checkout API Errors 138 July 2006 Website Payments Pro Integration Guide . Short Message.Express Checkout API Error Codes.

This transaction cannot be processed. You must submit an IP address of the buyer with each API call The credit card type entered is not currently supported by PayPal The merchant selected an value for the PaymentAction field that is not supported 10505 Gateway Decline Invalid Configuration Invalid Data 10507 10508 10509 10510 10511 Invalid Data Invalid Data Invalid Data Website Payments Pro Integration Guide July 2006 139 . Please enter a valid credit card expiration date. The credit card type is not supported. This transaction cannot be processed due to an invalid merchant configuration.contact PayPal for more information The expiration date must be a two-digit month and four-digit year. Please use a valid credit card. Please enter a valid Credit Card Verification Number. This transaction cannot be processed. This transaction cannot be processed. Corrective Action Occurs when you have not agreed to the billing agreement Occurs when the billing agreement is disabled or inactive. This transaction cannot be processed. Your PayPal account is restricted . 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. This transaction cannot be processed. Please contact PayPal Customer Service. Try another card type. and Long Messages Direct Payment API Errors TABLE B. This transaction cannot be processed. The credit card used is expired Invalid Configuration Invalid Configuration Invalid Data 10501 10502 10504 Invalid Data The CVV provide is invalid. Short Message.1 Direct Payment API Errors Long Message This transaction cannot be processed due to an invalid merchant configuration. This transaction cannot be processed.B Error Code 10500 Short Message Direct Payment API Error Codes.

This transaction cannot be processed. To change this setting. 140 July 2006 Website Payments Pro Integration Guide . Contact PayPal for more information The credit card entered is invalid 10535 10536 The merchant entered an invoice ID that is already associated with a transaction by the same merchant. This transaction cannot be processed. Please enter a valid credit card number and type. Please enter a credit card. Corrective Action The first name of the buyer is required for this merchant The last name of the buyer is required for this merchant The credit card field was blank The total amount and item amounts do not match The credit card entered is invalid 10513 Invalid Data 10519 10520 10521 Invalid Data Invalid Data Invalid Data 10523 10525 Internal Error Invalid Data None . This transaction cannot be processed. the invoice ID must be unique for all transactions. This transaction cannot be processed. and Long Messages Direct Payment API Errors TABLE B. By default. The amount to be charged is zero. change your risk settings on PayPal.this is a PayPal internal error The merchant entered a amount of zero 10526 Invalid Data The currency code entered is not supported 10527 Invalid Data The credit card entered is invalid 10534 Gateway Decline Gateway Decline Invalid Data The credit card entered is currently restricted by PayPal. This transaction cannot be processed. Please enter a valid credit card. log into PayPal or contact customer service The transaction was declined by the country filter managed by the merchant. The currency is not supported at this time. This transaction cannot be processed. 10537 Filter Decline This transaction cannot be processed. Please enter a valid credit card number and type. This transaction cannot be processed. Please enter a valid credit card number and type.Direct Payment API Error Codes.1 Direct Payment API Errors Error Code 10512 Short Message Invalid Data Long Message This transaction cannot be processed. Short Message. This transaction cannot be processed. Please enter a last name. This transaction cannot be processed. Please enter a first name. To accept this transaction. This transaction cannot be processed.

This transaction cannot be processed. This transaction cannot be processed. The transaction cannot be processed due to an invalid address. The merchant's accouht is not able to process transactions. The transaction was declined by PayPal. This transaction cannot be processed. 10541 Gateway Decline Invalid Data 10542 10544 10545 Gateway Decline Gateway Decline Gateway Decline Internal Error Invalid Configuration 10546 10547 10548 10549 Invalid Configuration 10550 10552 Invalid Configuration Invalid Configuration Website Payments Pro Integration Guide July 2006 141 . and Long Messages Direct Payment API Errors TABLE B. To accept this transaction. Check your account settings 10539 10540 Filter Decline Invalid Data This transaction cannot be processed. The merchant account attempting the transaction does not have a confirmed email address with PayPal. Contact PayPal for more information The email address provided by the buyer is in an invalid format The transaction was declined by PayPal. Contact PayPal for more information The transaction was declined by PayPal because of possible fraudulent activity on the IP address.this is a PayPal internal error The merchant account attempting the transaction is not a business account at PayPal. Contact PayPal for more information The transaction was declined by PayPal because of possible fraudulent activity. The merchant's account is not able to process transactions. Corrective Action The transaction was declined by the maximum amount filter managed by the merchant. Access to Direct Payment was disabled for your account. Short Message. This transaction cannot be processed. change your risk settings on PayPal. Please enter a valid email address. This transaction cannot be processed. Contact PayPal for more information.1 Direct Payment API Errors Error Code 10538 Short Message Filter Decline Long Message This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. Please enter a valid credit card number and type. Contact PayPal for more information The transaction was declined by PayPal because of an invalid address. The credit card entered is currently restricted by PayPal. This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. Contact PayPal for more information None . Check your account settings The merchant account attempting the transaction is not able to process Direct Payment transactions. Contact PayPal for more information.Direct Payment API Error Codes.

the merchant has set to decline transaction when the AVS returned a no match (AVS = N) The transaction was declined because of a merchant risk filter for AVS.1 Direct Payment API Errors Error Code 10553 10554 Short Message Gateway Decline Filter Decline Long Message This transaction cannot be processed. Please enter a complete billing address. Please enter your five digit postal code in the billing address. Short Message. There's an error with this transaction. This transaction cannot be processed. 10556 Filter Decline This transaction cannot be processed. 10555 Filter Decline This transaction cannot be processed. 10701 Invalid Data There's an error with this transaction. There's an error with this transaction. Please enter a valid address2 in the billing address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Specifically. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter a valid state in the billing address. There's an error with this transaction. There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address. 10702 Invalid Data There was a problem with a particular field in the address. There's an error with this transaction. Specifically. Specifically.Direct Payment API Error Codes. The long error message will tell you what field is invalid There was a problem with a particular field in the address. the merchant has set to decline transaction when the AVS was unsupported The billing address entered is invalid. The long error message will tell you what field is invalid There was a problem with a particular field in the address. There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address. and Long Messages Direct Payment API Errors TABLE B. Please enter a valid address1 in the billing address. Please enter a valid country in the billing address. The long error message will tell you what field is invalid 10703 Invalid Data 10704 Invalid Data 10705 Invalid Data 10706 Invalid Data 10707 Invalid Data 10708 Invalid Data 142 July 2006 Website Payments Pro Integration Guide . Please enter a valid city in the billing address. Please enter a valid billing address. Corrective Action The merchant attempted a transaction where the amount exceeded the upper limit for that merchant The transaction was declined because of a merchant risk filter for AVS. There's an error with this transaction. the merchant has set to decline transaction when the AVS returned a partial match The transaction was declined because of a merchant risk filter for AVS.

There's an error with this transaction. There's an error with this transaction. Please enter a valid state in the billing address. Short Message. There's an error with this transaction. Please enter a country in the billing address. There's an error with this transaction. Please enter a city in the billing address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter your five digit postal code in the billing address. Please enter a city in the billing address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter your state in the billing address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. There's an error with this transaction. There's an error with this transaction. There's an error with this transaction.Direct Payment API Error Codes. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter a valid billing address. and Long Messages Direct Payment API Errors TABLE B. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter your five digit postal code in the billing address. There's an error with this transaction. There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter an address1 in the billing address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Corrective Action There was a problem with a particular field in the address. The long error message will tell you what field is invalid 10709 Invalid Data 10710 Invalid Data 10710 Invalid Data 10711 Invalid Data 10712 Invalid Data 10713 Invalid Data 10713 Invalid Data 10714 Invalid Data 10715 Invalid Data 10716 Invalid Data 10717 Invalid Data Website Payments Pro Integration Guide July 2006 143 . Please enter an address1 in the billing address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. There's an error with this transaction. Please enter a country in the billing address.1 Direct Payment API Errors Error Code 10709 Short Message Invalid Data Long Message There's an error with this transaction. Please enter your five digit postal code in the billing address.

There's an error with this transaction. Please enter an address1 in the shipping address. There's an error with this transaction. There's an error with this transaction. Please enter a valid address2 in the shipping address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter a valid address1 in the shipping address. There's an error with this transaction. There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address. There's an error with this transaction. Please enter your five digit postal code in the shipping address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter a complete shipping address. Please enter an address1 in the shipping address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter a complete shipping address. The long error message will tell you what field is invalid 10719 Invalid Data 10720 Invalid Data 10721 Invalid Data 10722 Invalid Data 10723 Invalid Data 10724 Invalid Data 10725 Invalid Data 10726 Invalid Data 10726 Invalid Data 10727 Invalid Data 10727 Invalid Data 144 July 2006 Website Payments Pro Integration Guide . Please enter a valid shipping address. There's an error with this transaction.Direct Payment API Error Codes. There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter a valid state in the shipping address. Short Message. Please enter a valid country in the shipping address. Corrective Action There was a problem with a particular field in the address. There's an error with this transaction. and Long Messages Direct Payment API Errors TABLE B. The long error message will tell you what field is invalid There was a problem with a particular field in the address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter a valid city in the shipping address. There's an error with this transaction. Please enter a valid city and state in the billing address. There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address.1 Direct Payment API Errors Error Code 10718 Short Message Invalid Data Long Message There's an error with this transaction.

Please enter a valid city and state in the shipping address. There's an error with this transaction. There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address. There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter a city in the shipping address. Please enter a valid state in the shipping address. Please enter a city in the shipping address. Short Message. The long error message will tell you what field is invalid 10728 Invalid Data 10729 Invalid Data 10730 Invalid Data 10731 Invalid Data 10731 Invalid Data 10732 Invalid Data 10733 Invalid Data 10734 Invalid Data 10735 Invalid Data 10736 Invalid Data Website Payments Pro Integration Guide July 2006 145 . The long error message will tell you what field is invalid There was a problem with a particular field in the address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. There's an error with this transaction. Please enter a country in the shipping address. Corrective Action There was a problem with a particular field in the address. Please enter your five digit postal code in the shipping address. There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address. and Long Messages Direct Payment API Errors TABLE B. Please enter your five digit postal code in the shipping address. Please enter a valid shipping address. There's an error with this transaction. There's an error with this transaction. Please enter your state in the shipping address. There's an error with this transaction.1 Direct Payment API Errors Error Code 10728 Short Message Invalid Data Long Message There's an error with this transaction. The long error message will tell you what field is invalid There was a problem with a particular field in the address. Please enter a country in the shipping address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. There's an error with this transaction. Please enter your five digit postal code in the shipping address.Direct Payment API Error Codes. The long error message will tell you what field is invalid There was a problem with a particular field in the address.

Contact PayPal if you wish to change this setting There was a problem with a particular field in the address. This transaction cannot be processed. Please enter a valid state in the billing address. The long error message will tell you what field is invalid There was a problem with a particular field in the address. The long error message will tell you what field is invalid The merchant provided an address either in the United States or Canada. There's been an error due to invalid API username and/or password. Please use a valid country on the billing address. This transaction cannot be processed. This transaction cannot be processed.456 The merchant's configuration requires a CVV to be entered. This transaction cannot be processed. Please enter a valid country code in the shipping address. Contact PayPal for more information The currency code entered by the merchant is not supported None . Short Message. There's an error with this transaction. and Long Messages Direct Payment API Errors TABLE B. Corrective Action There was a problem with a particular field in the address.Direct Payment API Error Codes. The country and billing address associated with this credit card do not match. The transaction cannot be processed. not PayPal.1 Direct Payment API Errors Error Code 10744 Short Message Invalid Data Long Message This transaction cannot be processed. The IP address must be in a format such as 123. This transaction cannot be processed without a Credit Card Verification number.123. The long error message will tell you what field is invalid The merchant entered an IP address that was in an invalid format. This transaction cannot be processed. but the state provided is not a valid state in either country The transaction was declined by the issuing bank. The merchant should attempt another card The transaction was declined by PayPal. Please enter a valid country code in the billing address. but no CVV was provided with this transaction. Please enter a valid state in the shipping address. The long error message will tell you what field is invalid There was a problem with a particular field in the address.456. This transaction cannot be processed due to an unsupported currency.this is a PayPal internal error 10745 Invalid Data 10746 Invalid Data 10747 Invalid Data 10748 Invalid Data 10750 Invalid Data 10751 Invalid Data 10752 Gateway Decline Gateway Decline Invalid Data 10754 10755 10756 Gateway Decline 10758 Invalid Configuration The API username or password is incorrect for this merchant 146 July 2006 Website Payments Pro Integration Guide . There's an error with this transaction.

The CVV is between 3-4 digits long None . This transaction cannot be processed. This transaction cannot be processed. This transaction cannot be processed. 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. Please enter a valid Credit Card Verification Number. not PayPal. Can occur when a buyer submits multiple. Please enter a valid credit card number and type. This transaction cannot be processed. This transaction cannot be processed. Corrective Action The transaction was declined by PayPal. identical transactions in quick succession The CVV provide is invalid. This transaction cannot be processed. Please use a valid credit card.1 Direct Payment API Errors Error Code 10759 Short Message Gateway Decline Invalid Configuration Long Message This transaction cannot be processed. The merchant should attempt another card 10760 10761 Gateway Decline 10762 10763 15001 Gateway Decline Invalid Data Gateway Decline 15002 15003 Gateway Decline Invalid Configuration This transaction cannot be processed. Contact PayPal for more information. The transaction was declined because the CVV entered does not match the credit card. This transaction cannot be processed. Please check the status of your first transaction before placing another order.this is a PayPal internal error The transaction was rejected by PayPal because of excessive failures over a short period of time for this credit card. Contact PayPal for more information The transaction was declined because the merchant does not have a valid commercial entity agreement on file with PayPal. This transaction cannot be processed. Contact PayPal for more information The transaction was declined by PayPal. This transaction cannot be processed. The merchant should attempt another card The transaction was declined by the issuing bank because of an expired credit card. not PayPal. The transaction was declined by the issuing bank. 15004 Gateway Decline Processor Decline Processor Decline Processor Decline This transaction cannot be processed.Direct Payment API Error Codes. 15005 15006 15007 Website Payments Pro Integration Guide July 2006 147 . Short Message. Please enter a valid credit card number and type. and Long Messages Direct Payment API Errors TABLE B. The country listed for your business address is not currently supported. The merchant should attempt another card The transaction was declined by the issuing bank.

Short Message. and Long Messages Direct Payment API Errors 148 July 2006 Website Payments Pro Integration Guide .Direct Payment API Error Codes.

10001 10001 10004 10007 10009 10010 Internal Error Internal Error Internal Error Permission denied Transaction refused Transaction refused because of an invalid argument. Authorization voided. Website Payments Pro Integration Guide July 2006 149 . 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.. Short Message. See additional error messages for details. Close the order or authorization. DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoVoid Close the order or authorization. Correcting This Error. Close the order or authorization..C Error Code Short Message Authorization & Capture API Error Codes. 10601 Authorization expired.1 Authorization & Capture API Error Messages Long Message Returned By API Call.. Authorization has already been completed. and Long Messages TABLE C. 10602 Authorization completed. 10600 Authorization is voided.. Authorization has expired.

The buyer account is restricted. 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 Contact PayPal Customer Service 10608 Funding source missing. Contact the buyer. Contact the buyer. Currency is not supported. 10603 The buyer is restricted. Amount specified exceeds allowable limit.1 Authorization & Capture API Error Messages Error Code Short Message Long Message Returned By API Call. 10609 Check the validity of the authorization ID and reattempt the request. Review the order to ensure customer and seller are both PayPal members.. Contact customer service. Contact PayPal Customer Service.. Buyer cannot pay. Short Message. Authorization & Capture feature is not enabled for the merchant.. and Long Messages TABLE C. Contact the buyer. 10610 Amount limit exceeded. please contact the buyer. Transaction rejected. Authorization transaction cannot be unilateral. Authorization & Capture feature unavailable. Invalid transactionID. Close the order.Authorization & Capture API Error Codes. 10611 10612 No more settlement. The funding source is missing. 10604 Authorization must include both buyer and seller. No more settlement for the authorization. Retry the request with a PayPal-supported currency.. Auth&Capture unavailable. Not enabled. It must include both buyer and seller to make an auth. Reattempt the request with a lower amount. Maxmimum number of allowable settlements has been reached. Transaction id is invalid. Unsupported currency. 150 July 2006 Website Payments Pro Integration Guide . DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization Correcting This Error.

1 Authorization & Capture API Error Messages Error Code Short Message Long Message Returned By API Call. Order has expired. Website Payments Pro Integration Guide July 2006 151 . 10616 DoReauthorization Capture or close the authorization 10617 Reauthorization is not allowed inside honor period. 10620 Order has already been voided. Short Message. and retry the request. not a reauthorization. Ensure that the currencies are the same.. expired or completed. 10613 Currency mismatch. Check the length of the invoice ID and reattempt the request. DoCapture Correcting This Error. not a reauthorization. 10621 Close this order. DoAuthorization DoCapture DoVoid DoAuthorization DoCapture DoVoid DoAuthorization DoCapture DoVoid Close this order. Cannot void reauth. Transaction already voided or expired.. and Long Messages TABLE C. 10622 Order is voided. 10618 DoAuthorization DoCapture DoReauthorization DoVoid DoCapture 10619 Invoice ID value exceeds maximum allowable length. Close the orde or authorizationr. Currency of capture must be the same as currency of authorization. Order is voided. Cannot reauth reauth. Maximum number of reauthorization allowed for the auth is reached. DoReauthorization Capture the authorization ro reauthorize outside of honor period. Maximum number of reauthorization allowed for the auth is reached. Reauthorizatio n not allowed..Authorization & Capture API Error Codes.. Close this order. You can reauthorize only the original authorization. Void the authorization. expired or completed. Order has already been voided. Invoice ID value exceeds maximum allowable length. 10614 DoVoid 10615 DoReauthorization Capture the reauthorization. You can void only the original authorization. Transaction has already been voided or expired. Order has expired.

This transaction cannot be processed at this time. Reattempt the request with a lower amount.1 Authorization & Capture API Error Messages Error Code Short Message Long Message Returned By API Call. Short Message. Check the item amount to ensure that it is not zero or negative. and Long Messages TABLE C.. Item amount is invalid. Risk Maximum number of authorization allowed for the order is reached. DoReauthorization Use DoAuthorization to authorize the an order. The amount exceeds the maximum amount for a single transaction. DoAuthorization DoCapture DoReauthorization DoVoid Correcting This Error. 10628 This transaction cannot be processed at this time. See additional error messages for details. 10624 10625 Payment has already been made for this InvoiceID.. See additional error messages for details.. Reauthorizatio n not allowed. Duplicate invoice Transaction refused because of an invalid argument. 10623 Maximum number of authorization allowed for the order is reached. DoAuthorization DoCapture DoReauthorization DoVoid Retry the request at a later time. Please try again later.. Item amount is invalid. 10626 Transaction refused due to risk model The invoice ID field is not supported for basic authorizations DoAuthorization DoCapture DoReauthorization DoAuthorization DoReauthorization DoVoid Contact the buyer. 10629 Reauthorization is not allowed for this type of authorization. Please try again later. DoAuthorization DoAuthorization DoCapture DoReauthorization Review the invoice ID and reattempt the request. Capture this order. The Invoice ID field can only be used with DoCapture.Authorization & Capture API Error Codes. 10627 Transaction refused because of an invalid argument. 10630 DoAuthorization DoCapture 152 July 2006 Website Payments Pro Integration Guide .

. reauthorized. It cannot directly be voided. 11094 This authorization cannot be voided. or captured against. or captured against. This authorization can only be handled through the marketplace which created it.1 Authorization & Capture API Error Messages Error Code Short Message Long Message Returned By API Call... Correcting This Error. Website Payments Pro Integration Guide July 2006 153 . Short Message. reauthorized..Authorization & Capture API Error Codes. and Long Messages TABLE C.

Authorization & Capture API Error Codes. and Long Messages 154 July 2006 Website Payments Pro Integration Guide . Short Message.

D Country ALBANIA ALGERIA Country Codes Country Code AF AX AL DZ AS AD AO AI AQ AG AR AM AW AU AT AZ BS BH BD BB BY BE BZ BJ 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 CENTRAL AFRICAN REPUBLIC CHAD CHILE CHINA CHRISTMAS ISLAND COCOS (KEELING) ISLANDS COLOMBIA Code BM BT BO BA BW BV BR IO BN BG BF BI KH CM CA CV KY CF TD CL CN CX CC CO AFGHANISTAN ÅLAND ISLANDS AMERICAN SAMOA ANDORRA ANGOLA ANGUILLA ANTARCTICA ANTIGUA AND BARBUDA ARGENTINA ARMENIA ARUBA AUSTRALIA AUSTRIA AZERBAIJAN BAHAMAS BAHRAIN BANGLADESH BARBADOS BELARUS BELGIUM BELIZE BENIN 155 .

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 EQUATORIAL GUINEA ERITREA ESTONIA ETHIOPIA FALKLAND ISLANDS (MALVINAS) FAROE ISLANDS FIJI FINLAND FRANCE FRENCH GUIANA FRENCH POLYNESIA Code KM CG CD CK CR CI HR CU CY CZ DK DJ DM DO EC EG SV GQ ER EE ET FK FO FJ FI FR GF PF Country FRENCH SOUTHERN TERRITORIES GABON GAMBIA GEORGIA GERMANY GHANA GIBRALTAR GREECE GREENLAND GRENADA GUADELOUPE GUAM GUATEMALA GUERNSEY GUINEA GUINEA-BISSAU GUYANA HAITI HEARD ISLAND AND MCDONALD ISLANDS HOLY SEE (VATICAN CITY STATE) HONDURAS HONG KONG HUNGARY ICELAND INDIA INDONESIA IRAN.Country Codes Country COMOROS CONGO CONGO. ISLAMIC REPUBLIC OF Code TF GA GM GE DE GH GI GR GL GD GP GU GT GG GN GW GY HT HM VA HN HK HU IS IN ID IR 156 .

THE FORMER YUGOSLAV REPUBLIC OF Code IQ IE IM IL IT JM JP JE JO KZ KE KI KP KR KW KG LA LV LB LS LR LY LI LT LU MO MK Country MADAGASCAR MALAWI MALAYSIA MALDIVES MALI MALTA MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MAYOTTE MEXICO MICRONESIA.Country Codes Country IRAQ IRELAND ISLE OF MAN ISRAEL ITALY JAMAICA JAPAN JERSEY JORDAN KAZAKHSTAN KENYA KIRIBATI KOREA. DEMOCRATIC PEOPLE'S REPUBLIC OF KOREA. REPUBLIC OF MONACO MONGOLIA MONTSERRAT MOROCCO MOZAMBIQUE MYANMAR NAMIBIA NAURU NEPAL NETHERLANDS NETHERLANDS ANTILLES NEW CALEDONIA NEW ZEALAND NICARAGUA NIGER Code MG MW MY MV ML MT MH MQ MR MU YT MX FM MD MC MN MS MA MZ MM NA NR NP NL AN NC NZ NI NE 157 . REPUBLIC OF KUWAIT KYRGYZSTAN LAO PEOPLE'S DEMOCRATIC REPUBLIC LATVIA LEBANON LESOTHO LIBERIA LIBYAN ARAB JAMAHIRIYA LIECHTENSTEIN LITHUANIA LUXEMBOURG MACAO MACEDONIA. FEDERATED STATES OF MOLDOVA.

PROVINCE OF CHINA TAJIKISTAN Code VC WS SM ST SA SN CS SC SL SG SK SI SB SO ZA GS ES LK SD SR SJ SZ SE CH SY TW TJ 158 . 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 Code NG NU NF MP NO OM PK PW PS PA PG PY PE PH PN PL PT PR QA RE RO RU RW SH KN LC PM Country SAINT VINCENT AND THE GRENADINES SAMOA SAN MARINO 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.Country Codes Country NIGERIA NIUE NORFOLK ISLAND NORTHERN MARIANA ISLANDS NORWAY OMAN PAKISTAN PALAU PALESTINIAN TERRITORY.

S.Country Codes Country TANZANIA. WALLIS AND FUTUNA WESTERN SAHARA Code TZ TH TL TG TK TO TT TN TR TM TC TV UG UA AE GB US UM UY UZ VU VE VN VG VI WF EH Country YEMEN ZAMBIA ZIMBABWE Code YE ZM ZW 159 . BRITISH VIRGIN ISLANDS. UNITED REPUBLIC OF THAILAND TIMOR-LESTE TOGO TOKELAU TONGA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS AND CAICOS ISLANDS TUVALU UGANDA UKRAINE UNITED ARAB EMIRATES UNITED KINGDOM UNITED STATES UNITED STATES MINOR OUTLYING ISLANDS URUGUAY UZBEKISTAN VANUATU VENEZUELA VIET NAM VIRGIN ISLANDS. U.

Country Codes 160 .

Glossary AVS Address Verification System. checkout The process that takes place on your website in which a buyer selects a method of payment for an order. capture The request for settlement. banking industry terminology. In U. version 2. a three-digit code printed on the back of a credit card to enhance fraud protection when the credit card number is used over the Internet or telephone. auth Short for “authorization. settle Short for “settlement.” In U. the settlement is the actual movement of funds from the buyer’s account to the merchant’s account.” Strictly defined. An accounting description of the purchase of one or more items the buyer has agreed to pay for. June 2006 161 . With Authorization & Capture. banking industry standard for confirming the postal address or telephone number associated with a credit card. reauth An initially authorized transaction amount must be reauthorized if the amount of the transaction increases more than 115% of the original authorization. A U. an auth is your means to verify that a PayPal member has sufficient funds to meet a payment obligation. to electronically check the validity of a credit card number.S. PayPal Standard Checkout refers to all PayPal products for use during buyer checkout except for PayPal Express Checkout.S.S. CVV2 Card Verification Value. credit card industry terminology. order An end result of a checkout.

Glossary void In the context of payment processing with Authorization & Capture. to cancel a prior reauthorization of a settlement amount. 162 June 2006 .

Sign up to vote on this title
UsefulNot useful