Home

PayPal Web Services API - 2006 Reference Manual

1. Appendix B Country Codes Index 6 July 2006 155 Web Services API Reference Table 1 1 Table 1 1 Table 2 1 Table 2 2 Table 2 3 Table 2 4 Table 2 5 Table 2 6 Table 2 7 Table 2 8 Table 3 1 Table 3 2 Table 4 1 Table 4 2 Table 4 3 Table 4 4 Table 4 5 Table 4 6 Table 4 7 Table 4 8 Table 4 9 Table 4 10 Table 5 1 Table 5 2 Table 5 3 Table 5 4 Table 5 5 Table 5 6 Table 5 7 Table 5 8 Web Services API Reference List of Tables Revision History es 15 PayPal Technical Documentation 17 Location of PayPal WSDL and XSD Files 22 Basic PayPal API Set up Concepts and Terminology 22 RequesterCredentials Authentication Elements SOAP Header 24 SOAP Service 25 Annotation of Generic SOAP 27 Annotation of Generic SOAP Response 29 PayPal Supported Currencies Currency Codes and Maximum Transaction Amounts 31 API Overview by Business Function and Service Endpoint 32 AbstractRequestType Fields 36 AbstractResponseType Fields 36 Authorization amp Capture API Names Purposes and Types of Authorization 39 DoCaptureRequest Fields 41 DoCaptureResponse Fields 42 Response PaymentlnfoType Elements 42 DoAut
2. 129 Table A 6 DoExpressCheckoutPayment API Errors 130 Table A 7 GetTransactionDetails API Errors 137 Table A 8 MassPay Errors 138 Table A 9 RefundTransaction Errors 143 Table A 10 TransactionSearch API Errors 146 8 July 2006 Web Services API Reference List of Tables Web Services Reference July 2006 9 6 List of Tables 10 July 2006 Web Services API Reference Figure 2 1 Figure 2 2 Figure 3 1 Figure 4 1 Figure 4 2 Figure 4 3 Figure 4 4 Figure 5 1 Figure 6 1 Figure 6 2 Figure 6 3 Figure 7 1 Figure 8 1 Figure 9 1 Figure 10 1 Web Services API Reference List of Figures PayPal Web Services High level Diagram Diagram of SOAP Request Envelope Core eBL Types DoCapture Types DoAuthorization Types DoVoid Types DoReauthorization Types DoDirectPayment Types SetExpressCheckout Types GetExpressCheckout Types DoExpressCheckoutPayment Types GetTransactionDetails Types MassPay Types RefundTransaction Types TransactionSearch Types July 2006 21 26 35 40 45 47 49 51 66 73 78 87 97 101 103 11 List of Figures 12 July 2006 Web Services API Reference Preface This Document This document PayPal Web Services API Reference which describes the PayPal Web Services Application Programming Interface API and servi
3. July 2006 TABLE A 5 GetExpressCheckoutDetails API Errors Error Codes and Messages for All PayPal APIs Express Checkout Errors Error Code 10001 10001 10001 10001 10004 10004 10004 10004 Short Message Internal Error Internal Error ButtonSource value truncated ButtonSource value truncated Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Invalid transaction type Transaction refused because of an invalid argument See additionalerror messages for details Long Message Internal Error Transaction failed due to internal error The transaction could not be loaded The transaction could not be loaded Transaction refused because of an invalid argument See additional error messages for details The transaction id is not valid You can not get the details for this type of transaction The transaction could not be loaded Correcting This Error July 2006 129 130 Error Codes and Messages for All PayPal APIs Express Checkout API Errors TABLE A 5 GetExpressCheckoutDetails API Errors Error Short Code Message Long Message Correcting This Error 10004 Transaction The transaction id is not valid refused because of an invalid argument See additional error messages for details
4. Character length and limitations characters Payer s last name Character length and limitations characters 20 single byte 25 single byte 25 single byte 25 single byte 12 single byte 25 single byte 25 single byte DataType xs string ebl PersonNameType ebl NameType ebl NameType ebl SuffixType ebl NameType ebl NameType Possible Values See description See description See description See description See description See description TABLE 6 8 Response AddressType Fields Element AddressStatus Name Streetl Descriptions Status of street address on file with PayPal Person s name associated with this address Character length and limitations characters First street address Character length and limitations 100 single byte characters 32 single byte Data Type ebl AddressStatus TypeCode xs string xs string Possible Values none Confirmed Unconfirmed See description See description July 2006 Web Services API Reference TABLE 6 8 Response AddressType Fields Express Checkout API NEA DoExpressCheckoutPayment Element Street2 CityName StateOr Province PostalCode Country 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 len
5. July 2006 139 140 Error Codes and Messages for All PayPal APIs MassPay API Errors TABLE A 8 MassPay API Errors Error Code 10004 10004 10004 10004 10004 Short Message Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Long Message Currency is not supported The amount is not a valid number The amount exceeds the max limit of a single mass pay item 1 The amount is less than equal to zero The unique id string length exceeds the maximum limit of 30 characters July 2006 Error Codes and Messages for All PayPal APIs MassPay API Errors TABLE A 8 MassPay API Errors Error Code 10004 10004 10007 10301 10303 10304 10305 10306 10307 10308 Short Message Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Permission denied User not allowed Restric
6. PayerBusiness AddressOwner AddressStatus Name Streetl Street2 CityName StateOrProvince Country Description Payer s suffix Character length and limitations 12 single byte characters Payment sender s country of residence using standard two character ISO 3166 country codes See Appendix Character length and limitations Two single byte characters Payer s business name Character length and limitations 127 single byte characters Includes the following elements eBay company that maintains this address Status of the address on file with PayPal Person s name associated with this address Character length and limitations 32 single byte alphanumeric characters First street address Character length and limitations 300 single byte alphanumeric characters Second street address Character length and limitations 300 single byte alphanumeric characters Name of city Character length and limitations 120 single byte alphanumeric characters State or province Character length and limitations 120 single byte alphanumeric characters Character limit Two single byte characters See Appendix Data Type and Possible Values ebl SuffixType ebl CountryCode Type xs string ebl AddressType ebl AddressOwner TypeCode xs token eBay PayPal ebl AddressStatus CodeType xs token None Confirmed Unconfirmed xs string xs string xs string xs string xs string ns
7. URUGUAY UZBEKISTAN VANUATU VENEZUELA VIET NAM VIRGIN ISLANDS BRITISH VIRGIN ISLANDS U S 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 153 Country Codes E Country YEMEN ZAMBIA ZIMBABWE Code YE ZM ZW m Country Codes 154 Index Symbols NET SDK Guide 18 A AbstractRequestType 35 36 AbstractResponseType 35 36 100 Ack 28 37 success response 29 Address 61 69 90 Address Verification System 62 AddressOverride 69 AddressOwner 90 AddressOwnerTypeCode 90 AddressStatus 90 AddressStatus CodeType 90 AddressType 56 69 82 90 AddressVerifyResponseType 40 45 47 49 51 66 73 TI 105 Amount 60 83 95 96 99 102 105 API Certificate 23 API password 24 API Signature 23 API username 24 api paypal com 32 33 api 3t paypal com 33 Auction 96 AuctionInfoType 96 AuctionItemNumber 105 authentication for all SOAP requests 24 Authorization amp Capture 32 AuthorizationID 62 84 AVS 62 AVSCode 62 B BalanceAffecting 105 BalanceTransfer 105 BasicAmount Type 92 Web Services API Reference BasicAmountType 54 55 60 67 68 80 81 83 84 85 105 107 BasicAmountType data type 32 Billpay 105 Build 37 Business 89 ButtonSource 81 BuyerEmail 71 BuyerID 96 C Canceled Reversal 43 93 CancelURL 68 Card Verification Value See CVV2 CardNum
8. 10007 Permission You do not have permissions to denied make this API call 10007 Permission You do not have permission to denied get the details of this transaction 10007 Permission You do not have permissions to denied make this API call 10408 Express Express Checkout token 15 Checkout missing token is missing 10409 You re not Express Checkout token was authorized to issued for a merchant account access this other than yours info 10410 Invalid token Invalid token 10411 This Express This Express Checkout session Checkout has expired Token value is no session has longer valid expired TABLE A 6 DoExpressCheckoutPayment API Errors Error Short Code 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 July 2006 TABLE A 6 DoExpressCheckoutPayment API Errors Error Codes and Messages for All PayPal APIs Express Checkout Errors Error Code 10001 10001 10004 10004 10007 10406 10408 10409 10410 Short Message ButtonSource value truncated Internal Error Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Permission denied Transaction refused because of an invali
9. 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 Xis the name of the variable for a multi item shopping cart amount 3 is the item amount for the third item in a multiple item shopping cart To convey additional information this document may also apply color and underlining to words or phrases that use the typefaces described above Such use is described below Text attribute How Used XXXXXX Hyperte
10. 10004 10007 Short Message Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Permission denied Long Message Correcting This Error The partial refund amount must be a positive amount You can not specify a partial amount with a full refund A transaction id 15 required Transaction class is not supported The transaction id is not valid You do not have permission to refund this transaction July 2006 Error Codes and Messages for All PayPal APIs RefundTransaction API Errors TABLE A 9 RefundTransaction API Errors Error Code 10007 10009 10009 10009 10009 10009 10009 10009 10009 10009 10009 10009 10009 Short Message Permission denied Transaction refused Transaction refused Transaction refused Transaction refused Transaction refused Transaction refused Transaction refused Transaction refused Transaction refused Transaction refused Transaction refused Transaction refused L
11. Authorization Failed Authentication Authorization Failed Authentication Authorization Long Message Correcting This Error Account is restricted Token is not valid API access is disabled for this account Client certificate is disabled Failed Restricted Account is restricted account Authorization amp Capture API Errors TABLE A 2 Authorization amp Capture API Error Messages Error Code 10001 10001 10004 10007 10009 10010 Short Message Internal Error Internal Error Internal Error Permission denied Transaction refused Transaction refused because of an invalid argument See additionalerror messages for details Returned By API Long Message Call Correcting This Error Internal Error Transaction failed due to internal error Invalid argument You do not have permissions to make this API call Account is locked or Retry the request at a later inactive time or close order Invalid argument 110 July 2006 TABLE A 2 Authorization amp Capture API Error Messages Error Codes and Messages for All PayPal APIs Authorization amp Capture API Errors Error Code 10600 10601 10602 10603 10604 10605 10606 10607 10608 10609 Short Message Authorization voided Authorization expired Authorization completed The buyer 15 restricted Authorization must include both buyer and seller Unsuppo
12. CityName Name of city xs string See description Yes Character length and limitations 40 single byte characters StateOr State or province Province string See description No Character length and limitations 40 single byte characters PostalCode U S ZIP code or other country specific postal code xs string See description No Character length and limitations 20 single byte characters Country Country code ebl CountryCode See Appendix B Yes Character limit Two single byte characters Type xs string July 2006 Web Services API Reference Express Checkout API NEA DoExpressCheckoutPayment TABLE 6 12 Request PaymentDetailsitem Type Fields Allowable Required Element Description Data Type Values Name Item name xs string See description No Character length and limitations 127 single byte characters Amount Cost of item ebl BasicAmount See description No NOTE You must set the currencyID attribute to Type 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 Number Item number xs string See description No Character length and limitations 127 single byte characters Quantity Item quantity xs string See
13. Diagram of TransactionSearch Types The following diagram represents the composition of the TransactionSearchRequestType and PaymentTransactionSearchResultsType elements FIGURE 10 1TransactionSearch Types Request Response TransactionSearchRequestType TransactionSearchResponseType StartDate PaymentTransactions EndDate Payer Receiver PaymentTransactionSearchResultType TransactionID Timestamp PayerName Timezone AuctionltemNumber InvoicelD Payer CardNumber PayerDisplayName TransactionClass TransactionID Amount Status CurrencyCode GrossAmount Status FeeAmount NetAmount Web Services API Reference July 2006 103 TransactionSearch API TransactionSearchRequest TransactionSearchRequest Request to search transaction history Fields TABLE 10 1 TransactionSearchRequest Fields Element Description Data Type Allowable Values Required StartDate The earliest transaction date at which to start the search xs dateTime Transaction specific Yes NOTE No wildcards are allowed The value must be in UTC GMT format EndDate The latest transaction date to be included in the search xs dateTime Transaction specific No Payer Search by the buyer s email address ebl EmailAddress Transaction specific No Character length and limitations 127 single byte Type alphanumeric characters xs string Receiver Search by the receiver s email address If the merchant ebl EmailAddress Transaction specific No account has on
14. FeeAmount 42 85 92 107 FeeRefundAmount 102 FirstName 60 76 89 105 First Party Access 23 FundsAdded 105 FundsWithdrawn 105 G GetTransactionDetails 33 GetTransactionDetailsRequest 88 103 GetTransactionDetailsRequestType 87 GetTransactionDetailsResponse 99 GetTransactionDetailsResponseType 87 GrossAmount 84 92 107 GrossRefundAmount 102 H HandlingTotal 55 81 HTTPS 25 In Progress 93 instant 42 Instant Payment Notification 33 Mass Payment API 97 RefundTransaction API 33 97 101 int not integer 31 Integration Center 17 InvoiceID 55 68 74 81 95 104 IPAddress 53 ItemTotal 54 80 J Java SDK Guide 18 L LastName 60 76 89 105 LocaleCode 69 LongMessage 29 Web Services API Reference MassPay 33 105 MassPayltem 98 MassPayltemType 98 MassPayRequest 97 MassPayRequestltemType 97 MassPayRequestType 97 MassPayResponseType 97 MaxAmount 68 Memo 102 MerchantSessionId 53 MiddleName 76 89 105 MoneyRequest 105 multiltem 96 N Name 83 90 95 NameType 76 89 NetAmount 107 NetRefund 102 NoShipping 69 Note 99 NotifyURL 81 Number 60 83 95 numeric data types 31 Options 96 OptionType 96 Order Management Integration Guide 18 OrderDescription 55 68 81 OrderTotal 54 67 80 P ParentTransactionID 91 Partially Refunded 93 Password 23 24 27 96 Payer 60 75 89 104 106 PayerBusiness 75 90 PayerCountry 75 90 PayerDisplayName 106 PayerID 75 79 89 99 PayerInfo 74
15. However because you already know the final Order Total 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 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 July 2006 125 Error Codes and Messages for All PayPal APIs Express Checkout API Errors TABLE A 4 SetExpressCheckout API Errors Error Short Code Message Long Message Correcting This Error 10415 Transaction A successful transaction has PayPal allows a token only once for a successful refused already been completed for this transaction because ofan token Handling this error invalid If you determine that your customers are clicking argument See your Place Order button twice PayPal additional error recommends that you disable the button after your messages for customer has clicked it details 10425 Express Express Checkout has been Checkout has disabled for this merchant Please been disabled contact Customer Service for this merchant 10432 Trans
16. PaymentDetails Details about each individual item included in the ebl PaymentDetails Table 5 6 on No Item order ItemType page 60 IMPORTANT Any fields in the WSDL or XSD files that are not described here are ignored For example do not set CountryName TABLE 5 4 Request ShipToAddress AddressType Fields Allowable Required Element Descriptions Data Type Values Name Person s name associated with this address xs string See description Yes Character length and limitations 32 single byte characters Streetl First street address xs string See description Yes Character length and limitations 100 single byte characters Street2 Second street address xs string See description No Character length and limitations 100 single byte characters CityName Name of city xs string See description Yes Character length and limitations 40 single byte characters StateOr State or province xs string See Table 5 5 on No Character length and limitations 40 single byte page 57 characters PostalCode U S ZIP code or other country specific postal code xs string See description No Character length and limitations 20 single byte characters 56 July 2006 Web Services API Reference Direct Payment API NA DoDirectPaymentRequest TABLE 5 4 Request ShipToAddress AddressType Fields Allowable Required Element Descriptions Data Type Values Country Country code eb1 CountryCode See Appendix B Yes Character limit Two single byt
17. Quantity set by you or entered by the customer Character length and limitations no limit Cost of item Data Type and Possible Values ebl ReasonCodeType xs token none chargeback guarantee buyer complaint refund other ebl PaymentItem InfoType xs string xs string xs string xs string xs string xs string xs string ebl BasicAmount Type Web Services API Reference July 2006 95 GetTransactionDetails API GetTransactionDetailsResponse TABLE 7 2 GetTransactionDetailsResponse Fields Element Subscription Subscription TermsType Auction Included Element Options SubscriptionID SubscriptionDate EffectiveDate RetryTime Username Password Recurrences reattempt recurring Amount period BuyerID ClosingDate multiltem Description PayPal item options for shopping cart Includes the following elements ID generated by PayPal for the subscriber Character length and limitations no limit Subscription start date Date when the subscription modification will be effective Date PayPal will retry a failed subscription payment Username generated by PayPal and given to subscriber to access the subscription Character length and limitations 64 alphanumeric single byte characters Password generated by PayPal and given to subscriber to access the subscription For security the value of the password is hashed Character length and limitations 128 alpha
18. e Authorization amp Capture Integration Guide e Sandbox User Guide e API Reference other PayPal guides for an understanding of how products work None Website Payments Standard Integration Guide None Open Standards Background Information This section contains references to background information for understanding and using the PayPal Web Services API July 2006 Web Services API Reference Overview of the PayPal Web Services API Web Services Standards Web Services Standards Web Services are an ongoing open standards effort For the latest information about developments in Web Services see the following site http www webservices org Cryptography The PayPal Web Services API uses public key infrastructure specifically PKCS 12 and Privacy Enhanced Mail PEM For more information about PKCS 12 and PEM files see the following sites e PKCS12 and other forms of securely available credentials http www fags org rfcs rfc3157 html e PEM http www ietf org rfe rfc1421 txt Web Services API Reference July 2006 19 Overview of the PayPal Web Services Cryptography 20 July 2006 Web Services API Reference PayPal Web Services Architecture The PayPal Web Services API provides programmatic access to PayPal features and services Developers can build custom applications tools and services that correspond to the same services and tools available
19. his permission to make API calls for him Examples A web hosting service has its own API certificate API username and API password Its customers who are merchants that use PayPal give the hosting service their permission to make API calls on their behalf The hosting service includes a merchant s API username in the Subject field of an API call A merchant company s programmer has her own PayPal issued API signature username and password She gives permission to a shopping cart service to access her API credentials The shopping cart service makes API calls on the programmer s company s behalf using the programmer s credentials Security The PayPal Web Services API service is protected to ensure that only authorized PayPal members use it There are three primary levels of security e username password and third party account authentication e Public private key encryption via an API certificate API signature Secure Sockets Layer SSL data transport A failure of authenticated security at any one of these levels denies access to the PayPal Web Services API Web Services API Reference July 2006 23 24 PayPal Web Services API Architecture Services Architecture SOAP RequesterCredentials Username Password Signature and Subject For the security of your business PayPal must verify that merchants or third party developers are permitted to initiate a transaction before they make one PayPal authenticates
20. 2006 Web Services API Reference Core eBL Request Response Structures The PayPal Web Services API is built on core structures from the eBL schema that define required elements in all SOAP requests and responses e AbstractRequestType e AbstractResponseType Diagram of core eBL Types The following diagram represents the composition of the AbstractRequestType and AbstractResponseType elements FIGURE 3 1 Core eBL Types Request Response AbstractRequestType AbstractResponseType DetailLevel Timestamp ErrorLanguage Ack MessagelD CorrelationID Version ShortMessage LongMessage ErrorCode SeverityCode ErrorParameters Web Services API Reference July 2006 35 Core eBL Request Response Structures AbstractRequestType AbstractRequestType AbstractRequestType is the base type definition of all PayPal Web Services SOAP requests IMPORTANT You must set the value of the Version element for all requests to any PayPal Web Services API Fields TABLE 3 1 AbstractRequestType Fields Element Description Data Type Allowable Values Required Version A string representing the version of the request payload xs string 2 0 Yes schema AbstractResponseType AbstractResponseType is the base type definition of all PayPal Web Services SOAP responses Fields For error codes and messages and their meanings see Appendix Error Codes and Messages for PayPal APIs TABLE 3 2 AbstractResponseType Fi
21. 25 SOAP Service 25 SOAP 26 SOAP Message Style 26 SOAP Request Envelope 26 Request 5 26 Response Structure 28 Error 29 CorrelationID for Reporting Problems to PayPal 30 Test Tools PayPal SDK Console 30 Web Services API Reference July 2006 eat Contents PayPal Web Services API 30 Character Encoding Data Types and Formats and Currencies 31 API Overview By Business Function and Service Endpoint 32 APIs to Exchange Funds or Display Information 33 Instant Payment Notification and the 5 33 Chapter 3 Core eBL Request Response Structures 35 Diagram of core eBL 35 AbstractRequestType 36 Fields 5 erd Ge de 36 AbstractResponseType 36 HIC IT 36 Chapter 4 Authorization amp Capture 39 Funds Availability 2 2 2 2 2 22 ss
22. 93 RefundPurposeTypeCodeType 102 RefundTransaction 33 RefundTransactionID 102 RefundTransactionRequest 101 102 RefundTransactionRequestType 101 RefundTransactionResponseType 101 RefundType 101 102 ReqConfirmShipping 69 RequesterCredentials 24 27 RetryTime 96 ReturnURL 68 Reversal 105 Reversed 43 93 Reversed transaction status 106 rpc encoding not supported 26 S SaleTax 95 Salutation 76 89 105 Sandbox User Guide 18 SDK 30 SDKs 17 security API password 24 API username 24 third party authorization 25 Sent 105 SettleAmount 85 92 Shipping 105 ShippingTotal 55 80 ShipToAddress 82 ShortMessage 29 Signature 23 24 27 endpoint sfor 25 SOAP request authentication 24 Software Development Kits 18 SSL 25 StartDate 104 StateOrProvince 61 90 Status 106 Street 61 90 Street2 61 90 Subject 23 24 25 27 Subscription 96 105 SubscriptionDate 96 SubscriptionID 96 Subscriptions and Recurring Payments Guide 18 SubscriptionTermsType 96 Success 29 37 Success transaction status 106 SuccessWithWarning 37 Suffix 76 90 105 SuffixType 76 90 Switch 53 T Tax 60 83 TaxAmount 85 92 TaxTotal 55 81 Third Party Access 23 third party authorization 24 25 Timestamp 28 36 106 format 31 Timezone 106 Token 67 74 79 84 transaction status search 106 TransactionClass 105 TransactionID 62 84 88 91 101 102 103 104 106 TransactionSearch 33 TransactionSearchRequest 103 106 TransactionSearchRequestType
23. Also includes information about Downloadable History Logs https www paypal com en US pdf PP OrderManagement IntegrationGuide pdf 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 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 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 Describes HTML FORM variables for using PayPal for subscriptions to goods and services https www paypal com en US pdf subscriptions pdf Details how to use the virtual terminal to accept credit card payments https www paypal com en US pdf VT user guide pdf Prerequisites Website Payments Standard Integration Guide e Website Payments Standard Integration Guide e Website Payments Pro Integration Guide
24. Country 90 July 2006 Web Services API Reference GetTransactionDetails API GetTransactionDetailsResponse TABLE 7 2 GetTransactionDetailsResponse Fields Element Included Element CountryName Phone PostalCode PaymentInfo ParentTransaction ID TransactionID ReceiptID TransactionType Description Expanded name of country Character length and limitations 64 single byte alphanumeric characters Phone number associated with this address Postal code Includes the following elements Original transaction to which this transaction is related This field is populated for the following transaction types e Reversal e Capture of an authorized transaction e Reauthorization of a transaction e Capture of an order The value of ParentTransactionID is the original orderID e Authorization of an order The value of ParentTransactionID is the original orderID e Capture of an order authorization e Void of an order The value of ParentTransactionID is the original orderID Character length and limitations 19 single byte characters PayPal transaction identification number Character length and limitations 19 single byte characters Receipt ID Character length and limitations 16 digits in XXXX XXXX XXXX XXXX format The type of transaction cart Transaction created by customer via the PayPal Shopping Cart feature send money Transaction created by customer from the Send Money tab on th
25. 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 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 Country IRAQ IRELAND ISLE OF MAN ISRAEL ITALY JAMAICA JAPAN JERSEY JORDAN KAZAKHSTAN KENYA KIRIBATI KOREA DEMOCRATIC PEOPLE S REPUBLIC OF KOREA REPUBLIC OF KUWAIT KYRGYZSTAN LAO PEOPLE S DEMOCRATIC REPUBLIC LATVIA LEBANON LESOTHO LIBERIA LIBYAN ARAB JAMAHIRIYA LIECHTENSTEIN LITHUANIA LUXEMBOURG MACAO MACEDONIA THE FORMER YUGOSLAV REPUBLIC OF Code IQ IE IM IL IT JM JP JE g KW KG LA LV LB LS LR LY LI LT LU MO MK Country Codes E Country MADAGASCAR MALAWI MALAYSIA MALDIVES MALI MALTA MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MAYOTTE MEXICO MICRONESIA FEDERATED STATES OF MOLDOVA REPUBLIC OF MONACO MONGOLIA MONTSERRAT MOROCCO MOZAMBIQUE MYANMAR NAMIBIA NAURU NEPAL NETHERLANDS NETHERLANDS ANTILLES NEW CALEDONIA NEW ZEALAND NICARAGUA NIGER Code MG MW MY MV ML MT MH MQ MR YT MX
26. Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Internal Error Invalid Data Invalid Data Long Message This transaction cannot be processed Please enter a valid Credit Card Verification Number This transaction cannot be processed This transaction cannot be processed Please contact PayPal Customer Service This transaction cannot be processed Please enter a valid credit card expiration date This transaction cannot be processed The credit card type is not supported Try another card type This transaction cannot be processed This transaction cannot be processed Please enter a first name This transaction cannot be processed Please enter a last name Please enter a credit card This transaction cannot be processed This transaction cannot be processed Please enter a valid credit card This transaction cannot be processed This transaction cannot be processed The amount to be charged is zero This transaction cannot be processed The currency is not supported at this time Corrective Action The CVV provide is invalid The CVV 15 between 3 4 digits long The transaction was refused because the AVS response returned the value of N and the merchant account is not able to accept such transactions Your PayPal account is restricted contact PayPal for more information The expiration date must be a
27. Note An informational note about this settlement that is xs string See description No displayed to the payer in email and in his transaction history Character length and limits 255 single byte characters DoVoidResponse Response to DoVoidRequest Fields TABLE 4 8 DoVoidResponse Fields Element Description Authorization The authorization identification number you ID specified in the request Character length and limits 19 single byte characters Data Type xs string Possible Values See description 48 July 2006 Web Services API Reference Authorization amp Capture Bd DoReauthorization DoReauthorization 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 DoExpressCheckout PaymentRequest PaymentAction element set to Authorization With 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 DoReauthoriz
28. RefundTransaction Types The following diagram represents the composition of the RefundTransactionRequestType and RefundTransactionResponseType elements FIGURE 9 1 RefundTransaction Types Request Response RefundTransactionRequestType RefundTransactionResponseT ype TransactionID RefundTransactionID RefundType FeeRefundA mount Amount NetRefundAmount Memo GrossRefundA mount RefundTransactionRequest Request to refund a payment With RefundTransactionRequest you must always pass the values of TransactionID and RefundType If RefundType is set to Full you must not set Amount however if RefundType is Partial you must set Amount Web Services API Reference July 2006 101 RefundTransaction API RefundTransactionResponse Fields TABLE 9 1 RefundTransactionRequest Fields Element Description Data Type Possible Values Required TransactionID Unique identifier of a transaction xs string Transaction specific Yes Character length and limitations 17 single byte alphanumeric characters RefundType Type of refund you are making ebl RefundPurpose Other Yes TypeCodeType Full xs token Partial Amount Refund amount ebl BasicAmount Transaction specific See Amount is required if Re undType 18 Partial Type description NOTE If RefundType is Full do not set Amount Memo Custom memo about the refund xs string Transaction specific No Character length and limitations 255 single byte alphanumeric characters RefundTr
29. Removed erroneous description that stated that the SetExpressCheckoutRequest field cpp header image must be URL encoded Web Services API Reference July 2006 15 Revision History 16 July 2006 Web Services API Reference Overview of the PayPal Web Services API The PayPal Web Services API provides programmatic access to PayPal features and services Developers can build custom applications tools and services that correspond to the same services and tools available through the main PayPal website https www paypal com Typical applications include searching for transactions paying en masse and making refunds 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 amp Capture Instant Payment Notification and more Visit the Integration Center at https www paypal com integration 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 1 1 PayPal Technical Documentation Guide Title Description Prerequisites Website Payments Details basic PayPal payment process for shopping cart and s
30. and limitations 127 single byte Type characters Required Yes 54 July 2006 Web Services API Reference TABLE 5 3 Request PaymentDetails Type Fields Direct Payment API DoDirectPaymentRequest Element ShippingTotal HandlingTotal TaxTotal Order Description Custom InvoiceID ButtonSource Description 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 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 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 Description of items the customer is purchasing Character length and limitations 12
31. byte characters Web Services API Reference July 2006 61 62 Direct Payment DoDirectPaymentResponse DoDirectPaymentResponse Response to DoDirectPaymentRequest The Direct Payment API response contains the Transaction D is your record of the transaction processed with PayPal In the D 1s your key to capturing funds with PayPal final Sale Transaction case of an Authorization Transaction Authorization amp Capture element In the case of a DoDirectPaymentResponse also returns the result of checking the buyer s postal address and credit card number as submitted by you with rectPaymentRequest against the U S banking industry standard Address Verification System AVS and Credit Card Verification CV V2 system Fields TABLE 5 9 DoDirectPaymentResponse Fields Element Description Data Type Possible Values TransactionID Unique transaction ID of the payment xs string See description IMPORTANT If the Paymentaction of the request was Authorization the value of TransactionID is your AuthorizationID for use with the Authorization amp Capture APIs Character length and limitations 19 single byte characters Amount The amount of the payment as specified by you ebl BasicAmount See description DoDirectPaymentRequest Type AVSCode Address Verification System response code xs string See Table 5 10 Character limit One single byte alphanumeric AVS Response character Codes on
32. description No Character length and limitations Any positive integer Tax Item sales tax ebl BasicAmount See description No Currency code must be set the same as for Type 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 DoExpressCheckoutPaymentResponse Response to DoExpressCheckoutPaymentRequest Web Services API Reference July 2006 83 84 Express Checkout API DoExpressCheckoutPayment Fields TABLE 6 13 DoExpressCheckoutPaymentResponse Fields Element Description Data Type Possible Values Token The timestamped token value that was returned by xs string See the description SetExpressCheckoutResponse and passed of Token on on page 72 GetExpressCheckoutDetailsRequest Character length and limitations 20 single byte characters PaymentInfo Information about the payment ebl Payment Info See Table 6 14 on Type page 84 TABLE 6 14 Response PaymentinfoType Elements Element Description Data Type Possible Values TransactionID Unique transaction ID of the payment xs string Transaction IMPORTANT If the Paymentaction of the request specific was Aut
33. in the shipping address There s an error with this transaction Please enter your state in the shipping address There s an error with this transaction Please enter your five digit postal code in the shipping address There s an error with this transaction Please enter a country in the shipping 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 The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The
34. indicated with an asterisk FIGURE 6 1 SetExpressCheckout Types Request SetExpressCheckoutRequestDetailsType OrderTotal ReturnURL CancelURL Token MaxAmount OrderDescription Custom InvoicelD ReqConfirmShipping NoShipping AddressOverride LocaleCode PageStyle cpp header image cpp header border color cpp header back color cpp payflow color Address PaymentAction BuyerEmail PaymentActionCodeType Authorization Order Sale AddressType Name Street Street2 CityName StateOrProvince PostalCode Country July 2006 Response SetExpressCheckoutResponseT ype Token Web Services API Reference Express Checkout API NEA 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 1 SetExpressCheckoutRequest Fields Allowable Required Element Description Data Type Values Token On your first invocation of ebl Express See the description No SetExpressCheckoutRequest the value of CheckoutTokenType of Token on this token is returned by page 72 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 ed
35. 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 The currencies of the shopping refused cart amounts must be the same because of an invalid argument See additional error messages for details 10419 Express Express Checkout PayerID is Checkout missing PayerID 15 missing 10420 Transaction Express Checkout refused PaymentAction is missing because of an invalid argument See additional error messages for details July 2006 133 134 Error Codes and Messages for All PayPal APIs Express Checkout Errors TABLE A 6 DoExpressCheckoutPayment API Errors Error Code 10421 10422 10423 10424 10431 Short Message This Express Checkout session belongs to a different customer Customer must choose new funding sources Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Item amount is invalid Long Messag
36. seller If you are the recipient of the payment and the payment is sent to your non primary email address the value of Receiver is still your primary email address Character length and limitations 127 single byte alphanumeric characters Unique account ID of the payment recipient the seller This value is the same as the value of the recipient s referral ID Includes elements described below Email address of payer Character length and limitations 127 single byte characters Unique customer ID Character length and limitations 17 single byte characters Status of payer s email address 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 Data Type and Possible Values ebl ReceiverInfo Type xs string xs string xs string ebl PayerInfo Type ns EmailAddress Type ebl UserIDType ebl PayPalUser StatusCodeType Verified Unverified xs string ebl NameType ebl NameType ebl NameType Web Services API Reference July 2006 89 GetTransactionDetails API GetTransactionDetailsResponse TABLE 7 2 GetTransactionDetailsResponse Fields Element Address included in PayerInfo Included Element Suffix PayerCountry
37. single byte characters maximum PaymentInfo Information about the payment ebl PaymentInfo See Table 4 4 on Type page 42 TABLE 4 4 Response PaymentinfoType Elements Element Description Data Type Possible Values TransactionID Unique transaction ID of the payment xs string Transaction Character length and limitations 17 single byte specific characters Transaction The type of transaction ns Payment cart Type Character length and limitations 15 single byte TransactionCode a d M characters Type PaymentType Indicates whether the payment is instant or delayed eb1 PaymentCode none Character length and limitations Seven single byte Type echeck characters xs string instant PaymentDate Time date stamp of payment xs dateTime Transaction specific GrossAmount The final amount charged including any shipping eb1 BasicAmountTyp Transaction and taxes form your Merchant Profile 5 specific FeeAmount PayPal fee amount charged for the transaction ebl BasicAmountTyp Transaction specific SettleAmount Amount deposited in your PayPal account after a ebl BasicAmountTyp Transaction currency conversion specific 42 July 2006 Web Services API Reference Authorization amp Capture API DoCapture TABLE 4 4 Response PaymentinfoType Elements Element Description Data Type Possible Values TaxAmount Tax charged on the transaction ebl BasicAmount Transaction specific xs string ExchangeRate Exchange rate if a currency conversion o
38. was declined by PayPal because of possible fraudulent activity on the IP address Contact PayPal for more information None this is a PayPal internal error The merchant account attempting the transaction is not a business account at PayPal Check your account settings The merchant account attempting the transaction is not able to process Direct Payment transactions Contact PayPal for more information Access to Direct Payment was disabled for your account Contact PayPal for more information The merchant account attempting the transaction does not have a confirmed email address with PayPal Check your account settings 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 Specifically the merchant has set to decline transaction when the AVS returned a no match AVS 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 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 The billing address entered is invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid July 2006 117 118 Error Codes and Messages
39. 103 TransactionSearchResponse 103 TransactionType 84 95 Type 106 July 2006 Web Services API Reference U Unicode 31 UniquelD 99 UserID 98 UserIDType 75 89 Username 23 24 27 96 UTC GMT 29 31 36 106 V Version 27 36 37 Virtual Terminal User Guide 18 Voided 43 93 Web Services 19 21 Web Services API Reference 18 Website Payments Pro Integration Guide 17 Website Payments Standard Integration Guide 17 WSDL 21 22 location of PayPal WSDL configuration file 22 X XSD 21 location for PayPal Web Services 22 Web Services API Reference July 2006 159
40. 6 1 SetExpressCheckoutRequest Fields Allowable Required Element Description Data Type Values Address Customer s shipping address ebl AddressType See Table 6 20n NOTE If you include a shipping address and set page 71 the AddressOverride element on the request PayPal returns this same address in GetExpressCheckoutDetailsRes ponse ReqConfirm The value 1 indicates that you require that the xs string 0 No Shipping customer s shipping address on file with PayPal be 1 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 NoShipping The value 1 indicates that on the PayPal pages xs string 0 shipping address fields should be displayed whatsoever Character length and limitations Four single byte numeric character Address The value 1 indicates that the PayPal pages should xs string 0 No 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 LocaleCode Locale of pages displayed by PayPal during Express xs string AU OF en AU No Checkout DE de DE Character length and limitations Five s
41. 7 single byte alphanumeric characters A free form field for your own use Character length and limitations 256 single byte alphanumeric characters Your own invoice or tracking number as set by you in the Invoicerp element of SetExpressCheckoutRequest Character length and limitations 127 single byte alphanumeric characters An identification code for use by third party applications to identify transactions Character length and limitations 32 single byte alphanumeric characters Data Type Allowable Values ebl BasicAmount See description Type ebl BasicAmount See description Type ebl BasicAmount See description Type XS 5 5 5 string string string string See description See description See description See description Required No No No Web Services API Reference July 2006 55 TABLE 5 3 Request PaymentDetails Type Fields Direct Payment DoDirectPaymentRequest Element Description Data Type Allowable Values Required NotifyURL Your URL for receiving Instant Payment xs string See description No Notification IPN about this transaction NoTE If you do not specify NotifyuRt 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 ShipToAddress Address the order will be shipped to ebl AddressType See Table 5 4 on No page 56
42. 88 89 90 Web Services API Reference PayerInfo Type 89 PayerInfoType 74 PayerName 75 105 PayerStatus 75 89 PaymentAction 52 71 79 84 must be Authorization if CreditCard Type is Switch or Solo 53 PaymentAction CodeType 52 71 79 PaymentCodeType 42 84 PaymentDate 84 92 PaymentDetails 52 80 PaymentDetailsItem 56 82 PaymentDetailsItemType 56 82 PaymentDetailsType 80 PaymentInfo 84 88 91 PaymentInfo Type 91 PaymentInfoType 42 84 95 PaymentItemInfo 88 95 PaymentStatus 85 93 PaymentStatusCodeType 85 93 PaymentTransactionClassCodeType 105 PaymentTransactionCodeType 42 84 PaymentTransactions 106 PaymentTransactionSearchResultsType 103 PaymentTransactionStatusCodeType 106 PaymentType 84 92 PayPal supported currencies 31 PayPalSvc wsdl 22 PayPalUser StatusCodeType 89 PayPalUserStatusCodeType 75 Pending 43 93 Pending transaction status 106 PendingReason 43 86 94 PendingStatusCodeType 94 percentage value format 31 period 96 PersonNameType 105 Phone 91 PHP SDK Guide 18 PostalCode 61 91 Processed 43 93 Processing transaction status 106 Q Quantity 60 83 95 July 2006 157 158 Index R ReasonCode 43 93 95 ReasonCodeType 95 reattempt 96 ReceiptID 91 104 Received 105 Receiver 89 104 ReceiverEmail 99 ReceiverID 89 ReceiverInfo 88 89 ReceiverInfo Type 89 Recurrences 96 recurring 96 Referral 105 Refund transaction class 105 Refunded 43
43. An API signature is suitable for use with Microsoft Windows web servers or other shared web server configurations such as those used by web hosting services Multiple API signatures can be associated with your API username and password For security every time you view your API credential signature on https www paypal com a new signature is generated In your API calls you can use any ofthe signatures that PayPal generates for you All the signatures are equally valid until you remove your credentials by clicking Remove on the View API Signature page A PayPal generated identifying account name and password that you use specifically for making API calls You include your API username and password with every API call The API username and password are different from your PayPal login username email address and password An indicator in an API call of the merchant for whom the call is being made This is the programmatic aspect of third party authentication The value of the Subject field is the third party s API username A company makes API calls itself from its own server to PayPal s server The company has its own API certificate or API signature username and password Example A staff programmer for a merchant s company obtains a PayPal issued API certificate file and makes API calls for the company from the company s own web server Another person or company makes API calls on the merchant s behalf The merchant grants the third party
44. FM MD MC MN MS MA MZ MM NA NR NP NL AN NC NZ NI NE eat Country Codes 152 Country NIGERIA NIUE NORFOLK ISLAND NORTHERN MARIANA ISLANDS NORWAY OMAN PAKISTAN PALAU PALESTINIAN TERRITORY OCCUPIED PANAMA PAPUA NEW GUINEA PARAGUAY PERU PHILIPPINES PITCAIRN POLAND PORTUGAL PUERTO RICO QATAR REUNION ROMANIA RUSSIAN FEDERATION RWANDA SAINT HELENA SAINT KITTS AND NEVIS SAINT LUCIA SAINT PIERRE AND MIQUELON Code NG NU NF NO OM PK PW PS PA PG PY PE PH PN PL 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 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 SZ SE CH SY TW TJ Country TANZANIA 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
45. July 2006 39 pr Authorization amp Capture DoCapture DoCapture 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 4 1 DoCapture Types Request Response DoCaptureRequestT ype AuthorizationID DoCaptureResponseResponseDetailsType Amount AuthorizationID CompleteType PaymentInfo InvoicelD Note PaymentInfoType TransactionID TransactionT ype PaymentType PaymentDate GrossAmount FeeAmount SettleAmount TaxAmount ExchangeRate PaymentStatus PendingReason 40 July 2006 Web Services API Reference Authorization amp Capture ld DoCapture DoCaptureRequest Request to capture funds from a PayPal member s account Fields TABLE 4 2 DoCaptureRequest Fields Element Description Data Type Allowable Values Required Authorization The authorization identification number of the xs string See description Yes ID 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 Amount Amount to capture ebl BasicAmount Se
46. Kule XU SEE ARV GU Xen PE 98 MassPayResponse 100 Fields ad oe ee bee Son MK EEE su edo x d edem duds ed 100 Chapter 9 RefundTransaction API 101 Instant Payment 101 Diagram of RefundTransaction 101 RefundTransactionRequest 101 Fields 24 54 4 3 a Rem a Rc 65 vom d som ge d 102 Web Services API Reference July 2006 5 eat Contents RefundTransactionResponse Fields cc sa veu ae DURER eue X OS RUE Chapter 10 TransactionSearch API Diagram of TransactionSearch TransactionSearchRequest Fields 2 sem beh i TransactionSearchResponse Fields 5a eomm ASS REDE AS Appendix A Error Codes and Messages for PayPal APIs General API Authorization amp Capture Errors Direct Payments Errors Express Checkout API Errors GetTransactionDetails Errors MassPay Errors RefundTransaction TransactionSearch
47. PI Errors Error Short Code Message Long Message 10001 Internal Error Internal Error 10001 Internal Error Transaction failed due to internal error 10001 ButtonSource The transaction could not be value loaded truncated 10001 Internal Error Internal Error Correcting This Error July 2006 123 124 Error Codes and Messages for All PayPal APIs Express Checkout API Errors TABLE A 4 SetExpressCheckout API Errors Error Code 10004 10004 10007 10102 10402 10404 10405 Short Message Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Permission denied PaymentActio n of Order Temporarily Unavailable Authorization only is not allowed for merchant Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Long Message Correcting This Error Transaction refused because of an invalid argument See additional error messages for details The transaction id is not valid You do not have permissions to make this API call PaymentAction of Order is temporarily unavailable Please try later or use other PaymentAction This merchant account is not permitted to set PaymentAction to A
48. PayPal Web Services API Reference For Professional Use Only Currently only available in English A usage Professional Uniquement Disponible en Anglais uniquement pour l instant Last Updated July 2006 PayPal Web Services API Reference 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 iAS ISi 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 announce
49. Services API Reference Authorization amp Capture Bd DoVoid DoVoid 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 NorE 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 4 3 DoVoid Types Request Response DoVoidRequestType DoVoidResponseType AuthorizationID Pl uthorizatior Note Web Services API Reference July 2006 47 pr Authorization amp Capture API DoVoid DoVoidRequest Request to void a prior authorization Fields TABLE 4 7 DoVoidRequest Fields Element Description Data Type Allowable Values Required AuthorizationI value of the original authorization xs string See description Yes identification number returned by 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
50. URL ShipToAddress PaymentDetailsItem Response PaymentDetailsItemType Name Amount Number Quantity Tax July 2006 DoDirectPaymentResponseType Amount AVSCode CVV2Code TransactionID 51 52 Direct Payment API DoDirectPaymentRequest DoDirectPaymentRequest 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 e 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 e Set PaymentAction to Authorization ifthe 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 amp Capture to obtain payment In either case besides the PaymentAction element DoDirect PaymentRequest 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 Type Fields TABLE 5 1 DoDirectPaymentRequest Fields Allowable Required Element Description Data Type Values PaymentAction How you want to o
51. a Type The reason the payment is pending eb1 PendingStatus i CodeType none No pending reason Oda 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 1s 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 Possible Values none address echeck intl multi currency verify other July 2006 Web Services API Reference GetTransactionDetails The GetTransactionDetails API retrieves information about a single transaction Diagram of GetTransactionDetails Types The following diagram represents t
52. action Invoice ID value exceeds refused maximum allowable length because of an invalid argument See additionalerror messages for details 10433 Transaction Value of OrderDescription refused element has been truncated because of an invalid argument See additionalerror messages for details 10434 Transaction Value of Custom element has refused been truncated because of an invalid argument See additionalerror messages for details 126 July 2006 Error Codes and Messages for All PayPal APIs Express Checkout Errors TABLE A 4 SetExpressCheckout API Errors Error Code 10436 10437 10438 10439 10440 Short Message Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Long Message Correcting This Error PageStyle value exceeds maximum allowable length cpp header image value exceeds maximum allowable length cpp header image value exceeds maximum allowable length cpp header image value exceeds maximum allowable length cpp header
53. ansaction was declined by PayPal Contact PayPal for more information The transaction was declined by PayPal because of possible fraudulent activity Contact PayPal for more information July 2006 Error Codes and Messages for All PayPal APIs TABLE A 3 Direct Payment API Errors Direct Payments Errors Error Code 10546 10547 10548 10549 10550 10552 10553 10554 10555 10556 10701 10702 Short Message Gateway Decline Internal Error Invalid Configuration Invalid Configuration Invalid Configuration Invalid Configuration Gateway Decline Filter Decline Filter Decline Filter Decline Invalid Data Invalid Data Long Message This transaction cannot be processed This transaction cannot be processed This transaction cannot be processed The merchant s accouht is not able to process transactions This transaction cannot be processed The merchant s account is not able to process transactions This transaction cannot be processed This transaction cannot be processed This transaction cannot be processed This transaction cannot be processed This transaction cannot be processed This transaction cannot be processed There s an error with this transaction Please enter a valid billing address There s an error with this transaction Please enter a valid address1 in the billing address Corrective Action The transaction
54. ansactionResponse Response to RefundTransactionRequest Fields TABLE 9 2 RefundTransactionResponse Fields Element Refund TransactionID FeeRefund Amount GrossRefund Amount NetRefund Amount Description Unique transaction ID of the refund Character length and limitations 17 single byte characters Transaction fee refunded to original recipient of payment Amount of money refunded to original payer Amount subtracted from PayPal balance of original recipient of payment to make this refund Data Type xs string ebl BasicAmount Type ebl BasicAmount Type ebl BasicAmount Type Value See description See description See description See description 102 July 2006 Web Services API Reference TransactionSearch API With TransactionSearchRequest you must always set the StartDate field Some other behavior e Setting TransactionID overrides all other fields even the required StartDate field e The effect of setting other elements is additive or can alter the search criteria TransactionSearchResponse returns up to 100 matches Partial matches are displayed For example setting the TransactionSearchRequest FirstName to Jess returns results such as Jessica and Jesse The most important returned element is TransactionID which you can pass to GetTransactionDetailsRequest in order to retrieve all available information about a specific transaction
55. as not yet confirmed payment for this Express Checkout session The NotifyURL element value exceeds maximum allowable length The ButtonSource element value exceeds maximum allowable length Correcting This Error July 2006 135 136 Error Codes and Messages for All PayPal APIs Express Checkout Errors TABLE A 6 DoExpressCheckoutPayment API Errors Error Code 10443 10444 10445 10446 10537 10538 10539 Short Message Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details This transaction cannot be processed at this time Please try again later Unconfirmed email Risk Control Country Filter Failure Risk Control Max Amount Failure Payment declined by your Risk Controls settings PayPal Risk Model Long Message Correcting This Error This transaction cannot be completed with PaymentAction of Order The transaction currency specified must be the same as previously specified This transaction cannot be processed at this time Please try again later A confirmed email is required to make this API call The transaction was refused because the country was prohibited as a result of your Country Monitor Risk Control Settings The transaction was refused because the maximum amount was excceeded as a res
56. ation Types The following diagram represents the composition of the DoReauthorizationRequestType and DoReauthorizationResponseType elements Elements required in the request are marked with an asterisk FIGURE 4 4 DoReauthorization Types Request Response DoReauthorizationRequestType DoReauthorizationResponseType s mre uio AuthorizationI D AuthorizationID Amount Web Services API Reference July 2006 49 pr Authorization amp Capture API DoReauthorization DoReauthorizationRequest Request to use Authorization amp Capture to reauthorize a transaction Fields TABLE 4 9 DoReauthorizationRequest Fields Element Description Data Type Allowable Values Required Authorization value of a previously authorized transaction xs string Any previously Yes ID identification number returned by a PayPal product authorized PayPal transaction identification number 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 Amount Amount to reauthorize cc BasicAmount See description Yes Limitations Must not exceed 10 000 USD in any Type currency No currency symbol Decimal separator must be a period and the thousands separator must be a comma DoReauthorizationResponse Response to DoReauthorizationRequest Fields TABLE 4 10 DoReaut
57. authentication TABLE 2 2 Basic PayPal API Set up Concepts and Terminology Term Definition API Calls PayPal Application Programming Interface services by which companies can make payments search transactions refund payments view transaction information and other business functions 99 Business Partner business partner can also be known as hosting service third party e commerce service shopping cart provider online storefront or gateway 22 July 2006 Web Services API Reference PayPal Web Services Architecture Services Architecture TABLE 2 2 Basic PayPal API Set up Concepts and Terminology Term API Certificate API Signature API Username and Password Subject First Party Access Third Party Access Definition A PayPal generated unique digital certificate file that you download from the PayPal website and use on the client computer to encrypt the HTTPS requests of your API calls to PayPal s API server An API certificate is suitable if you have complete control over your own web server A PayPal generated unique digital signature a line of text or hash that you copy from PayPal s website and include in your API calls An alternative to API Certificate security Your digital signature your API username and your API password all together are called three token authentication because you include each of them as a programatic token in your API calls
58. ayment Web Services API Reference July 2006 45 46 Authorization amp Capture API DoAuthorization DoAuthorizationRequest Request to authorize all or part of a customer order amount Fields TABLE 4 5 DoAuthorizationRequest Fields Element TransactionID Amount TransactionEnt ity Description The value of the order s transaction identification number returned by a PayPal product Character length and limits 19 single byte characters maximum 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 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 Data Type xs string ebl BasicAmount Type ebl Transaction EntityType Allowable Values See description See description Order Required Yes Yes DoAuthorizationResponse Response to DoAuthorizationRequest Fields TABLE 4 6 DoAuthorizationResponse Fields Element TransactionID Amount Description An authorization identification number Character length and limits 17 single byte characters The amount you specified in the request Data Type xs string ebl BasicAmount Type Possible Values See description See description July 2006 Web
59. ber 104 CardOwner 54 Certificate 23 25 character encoding and character set UTF 8 31 CityName 61 90 Classic ASP Guide 18 ClosingDate 96 Completed 43 93 console SDK 30 ContactPhone 75 CoreComponentTypes xsd 22 CorrelationID 29 30 37 CorrelationId 28 Country 61 90 CountryCodeType 57 72 75 77 82 cpp header back color 70 cpp header border color 70 cpp payflow color 70 CreditCard 52 CreditCardNumber 53 CreditCardType 53 currency amount data type 32 currency codes 31 CurrencyCode 105 CurrencyConversions 105 July 2006 155 Index currencyID 54 55 60 67 68 80 81 83 99 105 currencyld must be GBP if CreditCardType is switch or Solo 53 currencyID required attribute 32 Custom 55 68 74 81 95 CustomCode 37 CVV2 54 CVV2Code 62 D date time values 31 dateTime data type 31 Denied 43 93 Denied transaction status 106 Direct Payment 32 Dividend 105 DoAuthorizationRequest 45 DoAuthorizationResponse 45 doc literal SOAP messaging 26 E eBL 22 30 eBLBaseComponents xsd 22 ECheck 105 echeck 42 EffectiveDate 96 EmailAddress 98 EmailAddress Type 89 EmailAddressType 71 75 99 104 106 EmailSubject 98 EndDate 104 ErrorCode 29 Errors 29 37 ExchangeRate 85 92 Expired 43 93 ExpMonth 53 Express Checkout 32 65 Express Checkout Integration Guide 17 ExpressCheckoutTokenType 67 ExpYear 53 F Failed 93 Failure 37 July 2006 FailureWithWarning 37 Fee 105
60. bl BasicAmount See description Type XS XS 5 5 5 string string string string string See description See description See description See description See description Required 2 No Web Services API Reference July 2006 81 82 Express Checkout API DoExpressCheckoutPayment TABLE 6 10 Request PaymentDetailsType Fields Allowable Required Element Description Data Type Values ShipToAddress Address the order will be shipped to ebl AddressType See Table 6 11 on page 82 PaymentDetails Details about each individual item included in the ebl PaymentDetails See Table 6 12 on No Teen order ItemType page 83 Norte 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 TABLE 6 11 Request ShipToAddress AddressType Fields Allowable Required Element Descriptions Data Type Values Name Person s name associated with this address xs string See description Yes Character length and limitations 32 single byte characters Streetl First street address xs string See description Yes Character length and limitations 100 single byte characters Street2 Second street address x Character length and limitations 100 single byte characters string See description No
61. btain payment ebl PaymentAction Default The No Authorization indicates that this payment is a CodeT ype transaction basic authorization subject to settlement with xs token resulting from PayPal Authorization amp Capture DoDirect Sale indicates that this is a final sale for which Payment you are requesting payment P t will be a Character length and limit Up to 13 single byte d alphabetic characters Sale NorE Order is not allowed for Direct Payment CreditCard Information about the credit card to be charged ebl CreditCard See Table 5 2 on Yes DetailsType page 53 PaymentDetails Information about the payment ebl PaymentDetails See Table 5 3 on Yes page 54 July 2006 Web Services API Reference TABLE 5 1 DoDirectPaymentRequest Fields Direct Payment API DoDirectPaymentRequest Allowable Required Element Description Data Type Values IPAddress IP address of the payer s browser as recorded in its xs string Any valid Internet Yes HTTP request to your website Protocol address 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 22 222 22 Merchant Your customer session identification token xs string No SessionId NOTE PayPal records this optional session identification token as an additional means to detect possible fraud Character length and limitations 64 sin
62. cannot obtain details of bank transfer withdrawals for example Character length and limitations 17 single byte alphanumeric characters GetTransactionDetailsResponse Response to GetTransactionDetailsRequest Norte Because a field is defined in the formal structure of GetTransactionDetailsResponse does not mean that that field 1s necessarily returned Data are returned in a response only if PayPal has recorded data that corresponds to the field Fields For error codes and messages and their meanings see Appendix Error Codes and Messages for PayPal APIs TABLE 7 2 GetTransactionDetailsResponse Fields Data Type and Element Included Element Description Possible Values Payment ReceiverInfo Wrapper structure Transaction PayerInfo Details PaymentInfo PaymentItem Info 88 July 2006 Web Services API Reference GetTransactionDetails API GetTransactionDetailsResponse TABLE 7 2 GetTransactionDetailsResponse Fields Element Included Element ReceiverInfo Business Receiver ReceiverID PayerInfo Payer PayerID PayerStatus PayerName Salutation included in PayerInfo FirstName MiddleName LastName Description Includes elements described below Email address or account ID of the payment recipient the seller Equivalent to Receiver if payment is sent to primary account Character length and limitations 127 single byte alphanumeric characters Primary email address of the payment recipient the
63. ccurred xs string Transaction Relevant only if you are billing in the customer s specific 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 PaymentStatus Status of the payment ebl PaymentStatus None CodeType Canceled Reversal The status of the payment 2 n ca ned None No status Denied Canceled Reversal This means a reversal has been Expired canceled For example you won a dispute with the Failed customer and the funds for the transaction that was Pending reversed have been returned to you Refunded Reversed Completed The payment has been completed and processed the funds have been added successfully to your voided 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 ifthe 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 ofreversal The funds have been removed from your account balance and returned to the buyer The reason for the reversal
64. ce replaces the edition issued March 2006 Intended Audience This document is written for programmers familiar with Web Services application programming standards such as the Simple Object Access Protocol SOAP the Web Services Description Language WSDL and XML Schema Definition XSD language Organization of This Document Chapter 1 Overview of the PayPal Web Services API presents high level information about the purposes of the API supported development environments and usage limits and fees Chapter 2 PayPal Web Services API Architecture describes the architecture of the API services its security features the PayPal SOAP and WSDL implementations and data characteristics such as character encodings currency and date time formats and other information The central chapters describe individual PayPal Web Services APIs for a variety of business functions Appendix A Error Codes and Messages for All PayPal APIs details specific errors and warnings for each individual PayPal Web Services API Notational Conventions This document uses typefaces to identify the characteristics of text These typefaces and the characteristics they imply are described below Web Services API Reference July 2006 13 Preface Documentation Problems 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
65. celD The totals of the cart item amounts do not match order amounts The amount exceeds the maximum amount for a single transaction A successful transaction has already been completed for this token You have exceeded the maximum number of payment attempts for this token Correcting This Error If you include any of the following element values with DoExpressCheckoutPayment the sum of their values must equal the value of OrderTotal e ItemTotal e ShippingTotal e HandlingTotal e 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 You can send a maximum of 10 DoExpressCheckoutPayment API calls for any single token value after which the token becomes invalid 132 July 2006 Error Codes and Messages for All PayPal APIs Express Checkout Errors TABLE A 6 DoExpressCheckoutPayment API Errors Error Short Code Message Long Message Correcting This Error 10417 Transaction The transaction cannot complete Itis possible that the payment method the customer cannot successfully Instruct the chooses on PayPal might not succeed when you complete customer to use an alternative send DoExpressCheckoutPayment The payment method most likely cause is that the customer s credit card failed bank authorization Another possible though rare cause is that the final OrderTotal
66. 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 X 5 5 string string string string string Allowable Required Values See description No See description No See description No See description No See description No July 2006 Web Services API Reference Express Checkout API NEA SetExpressCheckout TABLE 6 1 SetExpressCheckoutRequest Fields Allowable Required Element Description Data Type Values PaymentAction How you want to obtain payment ebl PaymentAction Default The No e Authorization indicates that this payment is a 2 e transaction basic authorization subject to settlement with resulting from PayPal Authorization amp Capture DoExpress e Order indicates that this payment is is an order Checkout authorization subject to settlement with PayPal Payment Authorization amp Capture Request will bea e sale indicates that this is a final sale for which ele you are requesting payment IMPORTANT You cannot set PaymentAction to 2 1 SetExpressCheckoutReque St and then change PaymentAction to Authorization 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 ebl EmailAddress See
67. cy decimal separator must be a period and the thousands separator must be a comma Equivalent to nine characters maximum for USD ItemTotal Sum of cost of all items in this order ebl BasicAmount See description No 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 Shipping Total shipping costs for this order ebl BasicAmount See description No Total 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 Type July 2006 Web Services API Reference TABLE 6 10 Request PaymentDetailsType Fields Express Checkout API DoExpressCheckoutPayment Element Handling Total TaxTotal Order Description Custom InvoiceID ButtonSource NotifyURL Description 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 cur
68. d argument See additionalerror messages for details Express Checkout token is missing You re not authorized to access this info Invalid token Long Message The transaction could not be loaded Internal Error Transaction refused because of an invalid argument See additional error messages for details The transaction id is not valid You do not have permissions to make this API call The PayerID value is invalid Express Checkout token is missing Express Checkout token was Issued for a merchant account other than yours Invalid token Correcting This Error July 2006 131 Error Codes and Messages for All PayPal APIs Express Checkout Errors TABLE A 6 DoExpressCheckoutPayment API Errors Error Code 10411 10412 10413 10414 10415 10416 Short Message This Express Checkout session has expired Duplicate invoice Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Long Message This Express Checkout session has expired Token value is no longer valid Payment has already been made for this Invoi
69. d or made available to anyone in the future Contents Preface 13 This Document ux em le ek gem E Ens qe a ee a 13 Intended 13 Organization of This Document 13 Notational Conventions 13 Documentation Problems 14 Revision History e ea s ll e ess 15 Chapter 1 Overview of the PayPal Web Services 17 Get Started Quickly Integration 17 Complementary Technical 17 Open Standards Background 18 Web Services 5 5 19 Cryptography 222 sss ls s ss os osos sos 19 Chapter 2 PayPal Web Services API Architecture 21 Services Architecture 21 PayPal WSDL XSD Schema 22 API Concepts and Terminology 22 SOCUFID Ko podus Kadare RR apt tne dio Se Unus pa 23 SOAP RequesterCredentials Username Password Signature and Subject 24 Public Private Key 25 SSL Data Transport oaa
70. d returned to the buyer The reason for the reversal is specified in the ReasonCode element Processed A payment has been accepted Voided This authorization has been voided Data Type and Possible Values ebl PaymentStatus CodeType xs token None Canceled Reversal Completed Denied Expired Failed In Progress Partially Re funded Pending Processed Re funded Reversed Voided Web Services API Reference July 2006 93 GetTransactionDetails API GetTransactionDetailsResponse TABLE 7 2 GetTransactionDetailsResponse Fields Element Included 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 To change your preference go to the Preferences section of your Profile authorization You set lt PaymentAction gt Authorization lt PaymentAction gt on SetExpressCheckoutRequest and have not yet captured funds 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 yo
71. description No checkout PayPal uses this value to pre fill the Type PayPal membership sign up portion of the PayPal login page Character length and limit 127 single byte alphanumeric characters 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 TABLE 6 2 Address Shipping Address AddressType Elements Allowable Element Descriptions Data Type Values Required Name Person s name associated with this shipping xs string See description No address Character length and limitations 32 single byte characters Web Services API Reference July 2006 71 Express Checkout API SetExpressCheckout TABLE 6 2 Address Shipping Address AddressType Elements Element Descriptions Data Type Streetl First street address xs string Character length and limitations 100 single byte characters Street2 Second street address xs string Character length and limitations 100 single byte characters CityName Name of city xs string Character length and limitations 40 single byte characters StateOr State or province xs string Character length and limitations 40 single byte characters PostalCode U S Zip code or other country specific postal code xs string Character length and limitations 20 single byte charac
72. e This Express Checkout session belongs to a different customer Token value mismatch The customer must return to PayPal to select new funding sources This transaction cannot be completed with PaymentAction of Authorization Shipping address is invalid Item amount is invalid Correcting This Error 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 Itis 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 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 ina single checkout session PayPal does allow the reverse however You can set PaymentAction to Authorization wi
73. e PayPal website web accept Transaction created by customer via Buy Now Donation or Auction Smart Logos Subscr Transaction created by customer via Subscription eot means end of subscription term merch pmt preapproved payment mass pay Transaction created via MassPay virtual terminal Transaction created via merchant virtual terminal Data Type and Possible Values xs string xs string xs string ebl PaymentInfo Type xs string xs string xs string ebl Payment TransactionCode Type xs token cart send money web accept subscr failed subscr cancelsubscr paymentsubscr signupsubscr eotsubscr modifymercht pmtmass payvirtual terminal Web Services API Reference July 2006 91 GetTransactionDetails API GetTransactionDetailsResponse TABLE 7 2 GetTransactionDetailsResponse Fields Data Type and Element Included Element Description Possible Values PaymentType The type of payment ebl PaymentCode Type xs string none echeck instant PaymentDate Date and time of payment xs dateTime GrossAmount Full amount of the customer s payment before xs string transaction fee is subtracted FeeAmount Transaction fee associated with the payment xs string SettleAmount Amount deposited into the account s primary balance ebl BasicAmount after a currency conversion from automatic conversion Type through your Payment Receiving Preferences or manual conversion through manually accepting a paym
74. e 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 Web Services API Reference July 2006 59 60 Direct Payment API DoDirectPaymentRequest TABLE 5 6 Request PaymentDetailsItemType Fields Allowable Required Element Description Data Type Values Name Item name xs string See description No Character length and limitations 127 single byte characters Amount Cost of item ebl BasicAmount See description No NOTE You must set the currencyID attribute to Type 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 Number Item number xs string See description No Character length and limitations 127 single byte characters Quantity Item quantity xs string See description No Character length and limitations Any positive integer Tax Item sales tax ebl BasicAmount See description No Character length and limitations any valid currency amount currency code is set the same as for OrderTotal TABLE 5 7 CardOwner PayerlnfoType Fields Allowable Required Element Description DataType Values Payer Email address of payer ns EmailAddress See description No Character length and limitatio
75. e characters Type xs string TABLE 5 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 Web Services API Reference July 2006 57 ESI Direct Payment API DoDirectPaymentRequest TABLE 5 5 StateOrProvince Abbreviations for Canada and U S Canadian Province or U S State 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 58 July 2006 Web Services API Reference Direct Payment API NR DoDirectPaymentRequest TABLE 5 5 StateOrProvince Abbreviations for Canada and U S Canadian Province or U S State 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 Tennesse
76. e description Yes Limitations Must not exceed 10 000 USD in any Type currency No currency symbol Decimal separator must be a period and the thousands separator must be a comma CompleteType Indicates if this capture is the last capture you intend eb1 Complete Default Yes to make The default is complete Complete NOTE If completeType is Complete any remaining NotComplete amount of the original reauthorized transaction is automatically voided Character length and limits 12 single byte alphanumeric characters InvoiceID Your invoice number or other identification xs string See description No number NorE 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 Note An informational note about this settlement that is xs string See description No displayed to the payer in email and in his transaction history Character length and limits 255 single byte characters Web Services API Reference July 2006 41 DoCapture Authorization amp Capture API DoCaptureResponse Response to DoCaptureRequest Fields TABLE 4 3 DoCaptureResponse Fields Element Description Data Type Possible Values Authorization The authorization identification number you xs string See description ID specified in the request Character length and limits 19
77. each request If the request cannot be authenticated a SOAP security fault is returned In the SOAP request header your SOAP client must set the Username Password elements to pass an API username password combination In addition you can set the Signature or Subject elements to specify your API signature string and an optional third party account email address for authentication The following is a partial example of the RequesterCredentials elements required for all SOAP requests For a correlation of these elements to the generic structure of an entire SOAP request see SOAP Request Envelope on page 26 lt SOAP ENV Header gt lt RequesterCredentials xmlns urn ebay api PayPalAPI xsi type ebl CustomSecurityHeaderType Credentials xmlns urn ebay apis eBLBaseComponents xsi type ebl UserIdPasswordType gt Username xsi type xs string gt api_usemame lt Username gt Password xsi type xs string gt api password Password Signature xsi type xs string gt api signature lt Signature gt Subject xsi type xs string authorizing account emailaddress lt Subject gt lt Credentials gt lt RequesterCredentials gt lt SOAP ENV Header gt where TABLE 2 3 RequesterCredentials Authentication Elements in SOAP Header Element Value Description lt Username gt api username Your username which is auto generated by PayPal when you apply for a digital certificate to use the PayPal Web Serv
78. ed for your business address is not currently supported This transaction cannot be processed Please check the status of your first transaction before placing another order This transaction cannot be processed This transaction cannot be processed This transaction cannot be processed Corrective Action The merchant provided an address either in the United States or Canada but the state provided 1s not a valid state in either country The transaction was declined by the issuing bank not PayPal The merchant should attempt another card The transaction was declined by PayPal Contact PayPal for more information The currency code entered by the merchant is not supported None this is a PayPal internal error The API username or password is incorrect for this merchant The transaction was declined by PayPal Contact PayPal for more information The merchant s country of residence listed in their PayPal account is not currently supported to allow Direct Payment transactions The transaction was declined because PayPal is currently processing a transaction by the same buyer for the same amount Can occur when a buyer submits multiple identical transactions in quick succession The CVV provide is invalid The CVV 15 between 3 4 digits long None 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 PayPa
79. eetl Number Street2 Quantity CityName Tax StateOr Province Country PostalCode July 2006 Response DoExpressCheckoutPaymentResponseDetailsType Token PaymentInfo PaymentInfoType Transactionl D TransactionType PaymentType PaymentDate GrossAmount FeeAmount SettleAmount TaxAmount ExchangeRate PaymentStatus PendingReason Web Services API Reference 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 9 DoExpressCheckoutPaymentRequest Fields Allowable Required Element Description Data Type Values Token The timestamped token value that was returned by xs string See description Yes SetExpressCheckoutResponse and passed on GetExpressCheckoutDetailsRequest Character length and limitations 20 single byte characters PaymentAction How you want to obtain payment ebl PaymentAction Default The No Authorization indicates that this payment isa CodeType transaction basic authorization subject to settlement with xs token resulting from PayPal Authorization amp Capture DoExpress e Order indicates that this payment is is an order Checkout authorization subject to settlemen
80. elds Element Description Data Type Possible Values Timestamp The date and time UTC GMT the response was xs dateTime Transaction specific generated by the PayPal Web Services service as a result of processing a request 36 July 2006 Web Services API Reference Core eBL Request Response Structures TABLE 3 2 AbstractResponseType Fields AbstractResponseType Element Ack CorrelationID Errors Version Build Description A token representing the application level acknowledgement code Contains one of the following enumerated values Success Request processing succeeded Failure Request processing failed SuccessWithWarning Request processing completed successfully but with some warning information that could be useful for the requesting application to process or record FailureWithWarning Request processing failed with some error and warning information that the requesting application should process to determine causes of failure CustomCode Reserved for internal or future use A string that identifies the exact API request that produced this response Character length 41 characters maximum Error code for debugging a response ErrorCode token defining the error code number ShortMessage string containing the error message LongMessage string describing the error message A string representing the version of the response payload schema A string representing the specific software build that
81. ent This amount is calculated after fees and taxes have been assessed TaxAmount Amount of tax for transaction xs string ExchangeRate Exchange rate for transaction xs string 92 July 2006 Web Services API Reference GetTransactionDetails API GetTransactionDetailsResponse TABLE 7 2 GetTransactionDetailsResponse Fields Element Included Element PaymentStatus Description The status of the payment None No status Canceled Reversal 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 ifthe payment was previously pending because of possible reasons described for the PendingReason element Expired This authorization has expired and cannot be captured Failed The payment has failed This happens only ifthe payment was made from your customer s bank account In Progress The transaction is in process of authorization and capture Partially Refunded The transaction has been partially refunded Pending The payment is pending See PendingReason on page 94 for more information Refunded You refunded the payment Reversed payment was reversed due to a chargeback or other type of reversal The funds have been removed from your account balance an
82. ent can specify a third party PayPal account by whom you are authorized to make this request For more details see lt Subject gt on page 25 The SOAP request for every PayPal API follows this element naming pattern The API s specific name is appended with Req and in this elementthe specific api name Request is nested Each specific name Request has a corresponding specific api name RequestType Web Services API Reference July 2006 27 PayPal Web Services Architecture SOAP Implementation TABLE 2 5 Annotation of Generic SOAP Request Lines Comment 22 The number of the PayPal Web Services API version is required on each SOAP request 24 For details about required and optional elements and values for specific requests see the description of individual APIs Response Structure The following is an annotated description of the structure of a SOAP response from the PayPal Web Services API EXAMPLE 2 1 General Structure of PayPal API SOAP Response Success 1 lt xml version 1 0 2 SOAP ENV Envelope xmlns SOAP I xmlns SOAP 3 NV http schemas xmlsoap org soap envelope 4 NC http schemas xmlsoap org soap encoding xmins xsi http www w3 org 2001 XMLSchema instance 6 xmins xsd http www w3 org 2001 XMLSchema 7 8 9 n FP n xmlns xs http www w3 org 2001 XMLSchema xmlns cc urn ebay apis CoreComponentTypes xmlns wsu ht
83. erations are defined directly in the PayPal API schema e Troubleshooting information The PayPal API returns information about elements that trigger errors July 2006 Web Services API Reference PayPal Web Services API Architecture E PayPal Web Services API Definitions e Backward compatibility The PayPal API is versioned so that business applications are backward compatible when new elements are introduced to the server side schema Note eBL defines many structures that are specific to processing auctions PayPal s Web Services schema includes these definitions to maintain compatibility with eBay s Web Services and for possible future joint use of Web Services across both eBay and PayPal The material in this book focuses only on those Web Services definitions pertinent to use of the PayPal Web Services API Character Encoding Data Types and Formats and Currencies This section details allowed character encoding and character sets date data types and formats UTF 8 Character Encoding The PayPal Web Services API service assumes that all data in SOAP requests is in Unicode specifically the Unicode or UCS Transformation Format 8 bit encoding form UTF 8 In SOAP responses the service always returns data in UTF 8 Numeric and Date Time Formats The PayPal Web Services API schema defines the following data types for numeric and date time values e Numeric data types int 32 bit not integer For percentage val
84. es and their meanings see Appendix Error Codes and Messages for PayPal APIs TABLE 10 2 PaymentTransactions Fields Element Description Data Type Possible Values Timestamp The date and time in UTC GMT format the transaction xs dateTime Transaction specific occurred Timezone The time zone of the transaction xs string Transaction specific Type The type of the transaction xs string Transaction specific Payer The email address of either the payer or the payment ebl EmailAddress Transaction specific recipient the If GrossAmount is positive Payer is recipient of the funds If GcossAmount is negative xs string Payer is the paying customer Payer Display name of the payer xs string Transaction specific DisplayName TransactionID transaction ID of the seller xs string Transaction specific Status The status of the transaction xs string Transaction specific For details about statuses see PaymentStatus on page 93 July 2006 Web Services API Reference TABLE 10 2 PaymentTransactions Fields TransactionSearch API TransactionSearchResponse Element Description GrossAmount The total gross amount charged including any profile shipping cost and taxes FeeAmount The fee that PayPal charged for the transaction NetAmount The net amount of the transaction Data Type ebl BasicAmount Type xs string BasicAmount Type xs string BasicAmount Type xs string Possible Values Tran
85. everityCode gt lt Errors gt lt CorrelationID xmlns urn ebay apis eBLBaseComponents gt debugging_info lt Version gt Version xmlns urn ebay apis eBLBaseComponents gt 1 000000 lt Version gt lt Build xmlns urn ebay apis eBLBaseComponents gt 1 0006 lt Build gt other elements in response lt SOAP ENV Body gt lt SOAP ENV Envelope CorrelationID for Reporting Problems to PayPal The value returned in CorrelationIDis important for PayPal to determine the precise cause of any error you might encounter We suggest that you capture the value of CorrelationID so you can report it to PayPal Test Tools PayPal SDK Console The PayPal SDK includes the console which is a good tool for testing and learning the PayPal Web Services API For more details about the console see the PayPal SDK Guides PayPal Web Services API Definitions The PayPal Web Services API comprises individual API definitions for specific business functions As a foundation the API relies on eBay Business Language eBL base and core components The core eBL structures AbstractRequestType and AbstractResponseType are the basis of the SOAP request and response of each PayPal API AbstractResponseType is also the framework for error messages common across all PayPal APIs PayPal has made some schema design decisions that can affect how businesses design their own applications e Enumerations Enum
86. f individual APIs for specific business uses and the individual APIs are grouped into two service endpoints TABLE 2 8 API Overview by Business Function and Service Endpoint Business Function Authorization amp Capture API Direct Payments API Express Checkout API SOAP Request Response Production Live Endpoint Test Sandbox Endpoint DoCaptureRequest api aa paypal com 2 0 api aa sandbox paypal com 2 0 DoCaptureResponse api aa 3t paypal com 2 0 DoAuthorizationRequest DoAuthorizationResponse DoVoidRequest DoVoidResponse DoReauthorizationRequest DoReauthorizationRespons e DoDirectPaymentRequest api aa paypal com 2 0 DoDirectPaymentResponse api aa 3t paypal com 2 0 SetExpressCheckoutReques api aa paypal com 2 0 api aa sandbox paypal com 2 0 t api aa 3t paypal com 2 0 SetExpressCheckoutRespon se GetExpressCheckoutDetail sRequest GetExpressCheckoutDetail sResponse DoExpressCheckoutPayment Request DoExpressCheckoutPayment Response 32 July 2006 Web Services API Reference PayPal Web Services API Architecture E PayPal Web Services API Definitions TABLE 2 8 API Overview by Business Function and Service Endpoint Business Function SOAP Request Response Production Live Endpoint Test Sandbox Endpoint GetTransaction GetTransactionDetailsReq api paypal com 2 0 api sandbox paypal com 2 0 Details API uest ap
87. for All PayPal APIs Direct Payments API Errors TABLE A 3 Direct Payment API Errors Error Code 10703 10704 10705 10706 10707 10708 10709 10709 10710 10710 10711 10712 Short Message Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Long Message There s an error with this transaction Please enter a valid address2 in the billing address There s an error with this transaction Please enter a valid city in the billing address There s an error with this transaction Please enter a valid state in the billing address 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 a valid country in the billing address There s an error with this transaction Please enter a complete billing address There s an error with this transaction Please enter an address in the billing address There s an error with this transaction Please enter an address in the billing address There s an error with this transaction Please enter a city in the billing address There s an error with this transaction Please enter a city in the billing address There s an error with this transaction Please enter your state in the billing address There s an e
88. form of digital certificates by PayPal These keys uniquely identify an API user to prove his authorization to access PayPal Web Services Each SOAP request 15 signed by your private key and PayPal Web Services processes a request only after authentication succeeds SSL Data Transport data must be transported over the Secure Hyper Text Transport Protocol also known as SHTTP or HTTPS which relies on the Secure Sockets Layer SSL data communications protocol SOAP Service Endpoints Depending on your chosen authentication mechanism your SOAP requests must be processed by different service endpoints TABLE 2 4 SOAP Service Endpoints Authentication Mechanism Live Production Endpoint Test Sandbox Endpoint API Signature https api 3t paypal com 2 0 https api aa 3t paypal com 2 0 https api sandbox paypal com 2 0 https api aa sandbox paypal com 2 0 API Certificate https api paypal com 2 0 d FER https api aa paypal com 2 0 Nore For the correspondence between API calls and their service endpoints see Table 2 8 API Overview by Business Function and Service Endpoint on page 32 Web Services API Reference July 2006 25 PayPal Web Services Architecture SOAP Implementation SOAP Implementation This section contains information about the PayPal Web Services SOAP implementation SOAP Message Style doc literal PayPal uses doc literal SOAP messaging not rpc encoding Wi
89. format The IP address must be in a format such as 123 456 123 456 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 There was a problem with a particular field in the address The long error message will tell you what field 1s invalid July 2006 121 122 Error Codes and Messages for All PayPal APIs Direct Payments API Errors TABLE A 3 Direct Payment API Errors Error Code 10751 10752 10754 10755 10756 10758 10759 10760 10761 10762 10763 15001 Short Message Invalid Data Gateway Decline Gateway Decline Invalid Data Gateway Decline Invalid Configuration Gateway Decline Invalid Configuration Gateway Decline Gateway Decline Invalid Data Gateway Decline Long Message There s an error with this transaction Please enter a valid state in the billing address This transaction cannot be processed This transaction cannot be processed This transaction cannot be processed due to an unsupported currency The transaction cannot be processed The country and billing address associated with this credit card do not match There s been an error due to invalid API username and or password This transaction cannot be processed Please enter a valid credit card number and type This transaction cannot be processed The country list
90. gle byte numeric characters TABLE 5 2 CreditCardDetailsType Fields Allowable Required Element Description Data Type Values CreditCardType Type of credit card ebl CreditCardType Visa Yes Character length and limitations Up to ten single byte alphabetic characters Discover Am IMPORTANT If the credit card type is Switch or Solo Switch See important note in 1 The value of PaymentAction must be description Authorization Solo See 2 The currencyId must be GBP important note in description CreditCard Credit card number xs string See description Yes Number Character length and limitations numeric characters only No spaces or punctutation Must conform with modulo and length required by each credit card type ExpMonth Credit card expiration month xs int See description Yes Character length and limitations Two single byte numeric characters including leading zero ExpYear Credit card expiration year xs int See description Yes Character length and limitations Four single byte numeric characters Web Services API Reference July 2006 53 ESI Direct Payment DoDirectPaymentRequest TABLE 5 2 CreditCardDetailsType Fields Element CVV2 CardOwner StartMonth StartYear IssueNumber Allowable Description Data Type Values Card Verification Value version 2 xs string See description NOTE You must include a CVV2 value for those credit cards that use CVV2 Required for Visa MasterCa
91. gth 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 xs string xs string xs string ebl CountryCode Type xs string Possible Values See description See description See description See description 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 Dol Dol ExpressCheckoutPaymentRequestType and ExpressCheckoutPaymenti are indicated with an asterisk Web Services API Reference July 2006 ResponseType elements Elements required in the request 77 78 Express Checkout API DoExpressCheckoutPayment FIGURE 6 3 DoExpressCheckoutPayment Types Request DoExpressCheckoutPaymentRequestDetails Type Token PaymentAction PayerID PaymentDetails PaymentActionCodeType Authorization Order Sale PaymentDetailsType OrderTotal OrderDescription ItemTotal ShippingTotal HandlingTotal TaxTotal Custom InvoicelD ButtonSource NotifyURL ShipToAddress PaymentDetailsItem PaymentDetailsItemType AddressType Name Name Amount Str
92. haracter currency codes for any of the supported PayPal currencies Search by currency code Data Type Allowable Values ebl PersonNameType Transaction specific xs string xs string Transaction specific ebl Payment See description TransactionClass CodeType xs token ebl BasicAmount Transaction specific Type xs string xs token Transaction specific Required No Web Services API Reference July 2006 105 106 TransactionSearch API TransactionSearchResponse TABLE 10 1 TransactionSearchRequest Fields Element Status Description Search by transaction status Pending The payment is pending The specific reason the payment is pending is returned by the GetTransactionDetails API PendingReason element For more information see PendingReason on page 94 Processing The payment is being processed Success The payment has been completed and the funds have been added successfully to your account balance Denied You denied the payment This happens only ifthe payment was previously pending 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 Data Type ebl Payment Transaction StatusCodeType xs token Allowable Values Pending Processing Success Denied Reversed TransactionSearchResponse Response to TransactionSearchRequest Fields For error codes and messag
93. he thousands separator is a comma Equivalent to nine characters maximum for USD Amount deposited in your PayPal account after a ebl BasicAmount currency conversion Type Tax charged on the transaction ebl BasicAmount Character length and limitations Does not Type exceed 10 000 USD in any currency No xs string currency symbol Regardless of currency decimal separator is a period and the thousands separator is a comma Equivalent to nine characters maximum for USD Exchange rate if a currency conversion occurred xs string 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 Status of the payment ebl PaymentStatus Completed The payment has been completed and CodeType the funds have been added successfully to your xs token account balance Pending The payment is pending See the PendingReason element for more information Possible Values Transaction specific Transaction specific Transaction specific Transaction specific Completed Pending Web Services API Reference July 2006 85 86 Express Checkout API DoExpressCheckoutPayment TABLE 6 14 Response PaymentinfoType Elements Element PendingReason Description Dat
94. he composition of the GetTransactionDetailsRequestTypeand GetTransactionDetailsResponseType elements FIGURE 7 1 GetTransactionDetails Types GetTransactionDetailsRequestType Request TransactionID Web Services API Reference PaymentinfoType TransactionID ParentTransactionID ReceiptID TransactionT ype PaymentT ype PaymentDate GrossAmount FeeAmount SettleAmount TaxAmount ExchangeRate PaymentStatus PendingReason ReasonCode Response GetTransactionDetailsResponseType PaymentTransaction Details ReceiverInfo PayerInfo PaymentInfo PaymentltemInfo ReceiverInfoType Business Receiver ReceiverID PaymentItemInfoType InvoicelD Custom Memo SalesTax PaymentItem Subscription u Auction SubscriptionInfoType AuctionInfoType July 2006 PayerInfoType Payer PayerlD PayerStatus PayerName PayerCountry PayerBusiness Address PersonNameType Salutation FirstName MiddleName LastName AddressType AddressStatus StateOrProvince PostalCode Country 87 GetTransactionDetails GetTransactionDetailsRequest GetTransactionDetailsRequest Get details about a transaction Fields TABLE 7 1 GetTransactionDetailsRequest Fields Element Description Data Type Possible Values Required TransactionID Unique identifier of a transaction xs string Transaction specific Yes NOTE The details for some kinds of transactions cannot be retrieved with GetTransactionDetailsRequest You
95. hitecture business object interfaces and network stubs from PayPal provided WSDL and XSD files that specify the PayPal SOAP message structure its contents and the PayPal API service bindings A business application works with data in the form of object properties to send and receive data by calling object methods The SOAP client handles the details of building the SOAP request sending it to the PayPal service and converting the response back to an object PayPal WSDL XSD Schema Definitions The PayPal Web Services schema and its underlying eBay Business Language eBL base and core components are required for developing applications with the PayPal Web Services API The following are the locations of the WSDL and XSD files TABLE 2 1 Location of PayPal WSDL and XSD Files Development and Test with the PayPal Sandbox API Service PayPal Schema https www sandbox paypal com wsdl PayPalSvc wsdl eBL Base https www sandbox paypal com wsdl eBLBaseComponents xsd Components and https www sandbox paypal com wsdl CoreComponentTypes xsd Component Types Production with Live PayPal Web Services API Service PayPal Schema https www paypal com wsdl PayPalSvc wsdl eBL Base http www paypal com wsdl eBLBaseComponents xsd Components and http www paypal com wsdl CoreComponentTypes xsd Component Types API Concepts and Terminology Here are some basic concepts and terminology relating to PayPal s API service and security
96. horization Or Order the value of TransactionID is your AuthorizationID for use with the Authorization amp Capture APIs Character length and limitations 19 single byte characters Transaction The type of transaction ns Payment cart Type Character length and limitations 15 single byte TransactionCode characters Type PaymentType Indicates whether the payment is instant or delayed eb1 PaymentCode none Character length and limitations Seven single byte echeck characters xsistring instant PaymentDate Time date stamp of payment xs dateTime Transaction specific GrossAmount The final amount charged including any shipping eb1 Basicamount Transaction and taxes from your Merchant Profile Type specific Character length and limitations Does not exceed 10 000 USD in any currency No currency symbol Regardless of currency decimal separator 15 a period and the thousands separator is a comma Equivalent to nine characters maximum for USD July 2006 Web Services API Reference Express Checkout API DoExpressCheckoutPayment TABLE 6 14 Response PaymentinfoType Elements Element FeeAmount SettleAmount TaxAmount ExchangeRate PaymentStatus Description Data Type PayPal fee amount charged for the transaction ebl BasicAmount Character length and limitations Does not Type exceed 10 000 USD in any currency No currency symbol Regardless of currency decimal separator is a period and t
97. horizationRequest Fields 46 DoAuthorizationResponse Fields 46 DoVoidRequest Fields 48 DoVoidResponse Fields 48 DoReauthorizationRequest Fields 50 DoReauthorizationResponse Fields 50 DoDirectPaymentRequest Fields 52 CreditCardDetailsType Fields 53 Request PaymentDetailsType Fields 54 Request ShipToAddress AddressType Fields 56 StateOrProvince Abbreviations for Canada 0 5 57 Request PaymentDetailsltemType Fields 60 CardOwner PayerlnfoType Fields 60 CardOwner AddressType 05 61 July 2006 SI List of Tables Table 5 9 DoDirectPaymentResponse 62 Table 5 10 AVS Response Codes 63 Table 5 11 CVV2 Response Codes 63 Table 6 1 SetExpressCheckoutRequest 67 Table 6 2 Address Shipping Address AddressType Elements 71 Table 6 3 SetExpressCheckoutResponse Fields 72 Table 6 4 GetExpressCheckoutDetailsRequest Fields 74 Table 6 5 GetExpressCheckoutDetailsResponse Fields 74 Table 6 6 Response PayerlnfoType Elements 75 Table 6 7 Response Paye
98. horizationResponse Fields Element Description Data Type Possible Values Authorization A new authorization identification number xs string See description ID Character length and limits 19 single byte characters 50 July 2006 Web Services API Reference 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 DoDi rectPaymentRequestTyp and DoDirectPaymentResponseType elements Elements required in the request are indicated with an asterisk FIGURE 5 1 DoDirectPayment Types Web Services API Reference Request DoDirectPaymentRequestDetailsType PaymentAction PaymentDetails CreditCard IPAddress MerchantSessionID CreditCardDetailsType CardOwner CreditCardType CreditCardNumber ExpMonth ExpYear 2 StartMonth StartYear IssueNumber PayerInfoType Payer PayerName Address CreditCardTypeType Amex Discover MasterCard Visa Switch Solo AddressType Street Street2 CityName StateOr Province Country PostalCode PaymentActionCodeType Authorization Sale PersonNameType FirstName LastName PaymentDetailsType OrderTotal OrderDescription ItemTotal ShippingTotal HandlingTotal TaxTotal Custom InvoicelD ButtonSource Notify
99. i 3t paypal com 2 0 GetTransactionDetailsRes ponse MassPay API MassPayRequest api paypal com 2 0 api sandbox paypal com 2 0 MassPayResponse api 3t paypal com 2 0 Refund RefundTransactionRequest api paypal com 2 0 api sandbox paypal com 2 0 Transaction API RefundTransactionRespons api 3t paypal com 2 0 e Transaction TransactionSearchRequest api paypal com 2 0 api sandbox paypal com 2 0 Search API TransactionSearchRespons api 3t paypal com 2 0 e APIs to Exchange Funds or Display Information PayPal Web Services APIs deal with business transactions However the APIs can be further categorized as follows e APIs that result in an exchange of funds Authorization amp Capture Direct Payment Express Checkout MassPay RefundTransaction e APIs that provide information about business transactions GetTransactionDetails TransactionSearch Instant Payment Notification and the APIs Use of a PayPal Web Services API that results in an exchange of funds triggers the sending of an Instant Payment Notification email to the recipient of the funds The APIs that send Instant Payment Notification email messages are as follows e MassPay e RefundTransaction For more information about Instant Payment Notification see the PayPal Order Management Integration Guide Web Services API Reference July 2006 33 PayPal Web Services Architecture PayPal Web Services API Definitions 34 July
100. i PayPalAPI 11 Credentials xmlns urn ebay apis eBLBaseComponents 12 lt Username gt api usemame lt Username gt 13 lt Password gt api_password lt Password gt 14 lt Signature gt 15 lt Subject gt 16 lt Credentials gt 17 lt RequesterCredentials gt 18 SOAP ENV Header 19 lt 5 gt 20 specific name Req xmlns urn ebay api PayPalAPI 21 specific api name Request xsi type ns specific_api_name_RequestType gt 23 Version xsi type xsd string service version Version gt 24 required or optional element xsi type some type here 25 data 26 required or optional elements gt 27 specific name Request 28 specific api name Req 29 SOAP ENV Body 30 SOAP ENV Envelope gt TABLE 2 5 Annotation of Generic SOAP Request Lines 12 13 14 15 19 through 27 Comment The Username and lt Password gt elements are part of the PayPal Web Services lt RequesterCredentials gt security authentication mechanism you must construct for every SOAP request header For details see SOAP RequesterCredentials Username Password Signature and Subject on page 24 The lt Signature gt element should include your API signature string if that is the kind of API credential you are using For more details see lt Signature gt on page 24 The Subject elem
101. ial refund on this refused transaction 10009 Transaction The account for the counterparty is locked refused or inactive 10009 Transaction You can not refund this type of transaction refused 10011 Invalid Transaction refused because of an invalid transaction id transaction id value value 11001 Transaction Transaction class is not supported refused because of an invalid argument See additional error messages for details TransactionSearch API Errors TABLE A 10 TransactionSearch API Errors Error Code Short Message Long Message 10001 Internal Error Internal Error 10001 ButtonSource value The transaction could not be loaded truncated 10003 Transaction refused because Start date is a required parameter of an invalid argument See additional error messages for details 10004 Transaction refused because Start date is invalid of an invalid argument See additional error messages for details 146 July 2006 Error Codes and Messages for All PayPal APIs TransactionSearch API Errors TABLE A 10 TransactionSearch API Errors Error Code 10004 10004 10004 10004 10004 10004 10004 10004 10004 10004 Short Message Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error mes
102. ices API You can see this value on https www paypal com in your Profile under API Access gt API Certificate Information NOTE The PayPal Sandbox User Guide contains details about how you can obtain digital certificates for use with the PayPal Web Services API Password api password Your API password which you specify when you apply for a digital certificate to use the PayPal Web Services API Signature api signature Your API signature if you use one NOTE The Signature element must be included in the SOAP header even if you do not rely on an API signature In this case set Signature with no value Signature July 2006 Web Services API Reference PayPal Web Services API Architecture BE SOAP Service Endpoints TABLE 2 3 RequesterCredentials Authentication Elements in SOAP Header Element Value Description Subject authorizing The email address of a third party for whom you are sending requests account to the PayPal Web Services API Your API username must have been emailaddress granted permission by this third party to make any particular PayPal API request NOTE The Subject element must be included in the SOAP header even if you are not making a request on someone else s behalf In this case set Subject with no value Subject Public Private Key Encryption Your security with the PayPal Web Services API relies on a set of public private security keys issued in the
103. image value exceeds maximum allowable length July 2006 127 128 Error Codes and Messages for All PayPal APIs Express Checkout API Errors TABLE A 4 SetExpressCheckout API Errors Error Code 10537 10538 10539 10725 10727 10728 10729 10730 10731 10736 Short Message Risk Control Country Filter Failure Risk Control Max Amount Failure Payment declined by your Risk Controls settings PayPal Risk Model 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 Correcting This Error The transaction was refused because the country was prohibited as a result of your Country Monitor Risk Control Settings The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk Control Settings Payment declined by your Risk Controls settings PayPal Risk Model There was an error in the Shipping Address Country field The field Shipping Address1 is required The field Shipping Address City is required The field Shipping Address State is required The field Shipping Address Postal Code is required The field Shipping Address Country is required A match of the Shipping Address City State and Postal Code failed
104. ingle byte FR fr FR alphabetic characters upper or lowercase GB Of en ITOrit IT JP ja JP US OF en US Web Services API Reference July 2006 69 70 Express Checkout API SetExpressCheckout TABLE 6 1 SetExpressCheckoutRequest Fields Element PageStyle cpp header image cpp header border color cpp header back color cpp payflow color 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 ofthe 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
105. ingle item purchase None Standard Integration Account Profile settings for variations on basic payment process Customization of Guide PayPal s payment pages HTML FORM variables for control of payment process https www paypal com en US pdf PP WebsitePaymentsStandard Integratio nGuide pdf Express Checkout Details use of Express Checkout API PayPal placement on merchants websites and Website Payments Integration Guide related business rules Standard Integration https www paypal com en US pdf PP ExpressCheckout IntegrationGuide p Guide df Website Payments Details use of Express Checkout and Direct Payment APIs PayPal placement on Website Payments Pro Integration Guide merchants websites and related business logic Standard Integration https www paypal com en US pdf PP WebsitePaymentsPro IntegrationGui Guide de pdf Web Services API Reference July 2006 17 Overview of the PayPal Web Services API Open Standards Background Information TABLE 1 1 PayPal Technical Documentation Guide Title Order Management Integration Guide Java SDK Guide NET SDK Guide Classic ASP Guide PHP SDK Guide Sandbox User Guide Web Services API Reference Subscriptions and Recurring Payments Guide Virtual Terminal User Guide Description 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
106. is specified in the ReasonCode element Processed payment has been accepted Voided An authorization for this transaction has been voided Web Services API Reference July 2006 43 44 Authorization amp Capture API DoCapture TABLE 4 4 Response PaymentinfoType Elements Element Description Data Type PendingReason PendingReason is returned in the ebl PendingStatus response only if PaymentStatus is CodeType Pending xs token 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
107. it his shipping address on PayPal Character length and limitations 20 single byte characters OrderTotal The total cost of the order to the customer If cc BasicAmount See description Yes shipping cost and tax charges are known include Type 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 Web Services API Reference July 2006 67 68 Express Checkout API SetExpressCheckout TABLE 6 1 SetExpressCheckoutRequest Fields Element MaxAmount Order Description Custom InvoiceID ReturnURL CancelURL Description 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 maxim
108. l The number of results were truncated Please change your search parameters if you wish to see all your results July 2006 Country AFGHANISTAN ALAND ISLANDS ALBANIA ALGERIA AMERICAN SAMOA ANDORRA ANGOLA ANGUILLA ANTARCTICA ANTIGUA AND BARBUDA ARGENTINA ARMENIA ARUBA AUSTRALIA AUSTRIA AZERBAIJAN BAHAMAS BAHRAIN BANGLADESH BARBADOS BELARUS BELGIUM BELIZE BENIN Code AF AL DZ AS AD AO AI AQ AG AR AM AW AU AT BS BH BD BB BY BE BZ BJ Country Codes 149 Country 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 eat Country Codes 150 Country COMOROS CONGO CONGO THE DEMOCRATIC REPUBLIC OF THE COOK ISLANDS COSTA RICA COTE D IVOIRE CROATIA CUBA CYPRUS CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA DOMINICAN REPUBLIC ECUADOR EGYPT EL SALVADOR EQUATORIAL GUINEA ERITREA ESTONIA ETHIOPIA FALKLAND ISLANDS MALVINAS FAROE ISLANDS FIJI FINLAND FRANCE FRENCH GUIANA FRENCH POLYNESIA Code CG CD CK CR HR CU 4 DK DJ DM
109. l for more information July 2006 Error Codes and Messages for All PayPal APIs TABLE A 3 Direct Payment API Errors Express Checkout Errors Error Short Code Message Long Message 15002 Gateway This transaction cannot be Decline processed 15003 Invalid This transaction cannot be Configuration processed 15004 Gateway This transaction cannot be Decline processed Please enter a valid Credit Card Verification Number 15005 Processor This transaction cannot be Decline processed 15006 Processor This transaction cannot be Decline processed Please enter a valid credit card number and type 15007 Processor This transaction cannot be Decline processed Please use a valid credit card Corrective Action The transaction was declined by PayPal Contact PayPal for more information The transaction was declined because the merchant does not have a valid commercial entity agreement on file with PayPal Contact PayPal for more information The transaction was declined because the CVV entered does not match the credit card The transaction was declined by the issuing bank not PayPal The merchant should attempt another card The transaction was declined by the issuing bank not PayPal The merchant should attempt another card The transaction was declined by the issuing bank because of an expired credit card The merchant should attempt another card Express Checkout API Errors TABLE A 4 SetExpressCheckout A
110. le byte Type characters PayerID Unique PayPal customer account number ebl UserIDType See description Character length and limitations 17 single byte characters maximum PayerStatus Status of payer ebl PayPalUser verified Character length and limitations 10 single byte StatusCodeType unverified alphabetic characters PayerName First and last name of payer ebl PersonNameType See Table 6 7 on page 76 PayerCountry Payer s country of residence in the form of ISO ebl CountryCode See Appendix B standard 3166 two character country codes Type Character length and limitations Two single byte characters PayerBusiness Payer s business name xs string See description Character length and limitations 127 single byte characters Address Payer s shipping address address information xs string See Table 6 8 on page 76 Web Services API Reference July 2006 75 76 Express Checkout API GetExpressCheckoutDetails TABLE 6 7 Response PayerName Elements Element Salutation FirstName MiddleName LastName Suffix FirstName LastName Description Payer s salutation Character length and limitations characters Payer s first name Character length and limitations characters Payer s middle name Character length and limitations characters Payer s last name Character length and limitations characters Payer s suffix Character length and limitations characters Payer s first name
111. lem with a particular field in the address The long error message will tell you what field is invalid July 2006 Error Codes and Messages for All PayPal APIs TABLE A 3 Direct Payment API Errors Direct Payments Errors Error Code 10713 10713 10714 10715 10716 10717 10718 10719 10720 10721 10722 10723 Short Message Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Long 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 country in the billing address There s an error with this transaction Please enter a valid billing address There s an error with this transaction Please enter a valid state in the billing address 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 your five digit postal code in the billing 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 Please enter a valid shipping address There s an error with this transaction Please enter a valid address1 in the shipping address There s an error with this
112. lement of SetExpressCheckoutRequest Character length and limitations 256 single byte alphanumeric characters Your own invoice or tracking number as set by you xs string in the Invoicerp element of SetExpressCheckoutRequest Character length and limitations 127 single byte alphanumeric characters Possible Values See the description of Token on page 72 See Table 6 6 on page 75 See description See description July 2006 Web Services API Reference Express Checkout API GetExpressCheckoutDetails TABLE 6 5 GetExpressCheckoutDetailsResponse Fields Element Description Data Type Possible Values ContactPhone Payer s contact telephone number xs string See description 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 15 XXX XXX XXXX for US numbers or XXX XXXXXXXX for international numbers 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 TABLE 6 6 Response PayerlInfoType Elements Element Description DataType Possible Values Payer Email address of payer ebl EmailAddress See description Character length and limitations 127 sing
113. licable Error Not applicable others 64 July 2006 Web Services API Reference Express Checkout API The Express Checkout API is the Website Payments Pro alternative to standard PayPal shopping cart processing IMPORTANT For a full understanding of the complete details about how to use PayPal Express Checkout consult the PayPal Express Checkout Integration Guide 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 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 5 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 Web Services API Reference July 2006 65 66 Express Checkout API SetExpressCheckout SetExpressCheckout 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
114. long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid July 2006 Error Codes and Messages for All PayPal APIs TABLE A 3 Direct Payment API Errors Direct Payments Errors Error Code 10732 10733 10734 10735 10736 10744 10745 10746 10747 10748 10750 Short Message Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Long Message There s an error with this transaction Please enter a valid shipping address There s an error with this transaction Please enter a valid state in the shipping address There s an error with this transaction Please enter your five digit postal code in the shipping address There s an error with this transaction Please enter your five digit postal code in the shipping address There s an error with this transaction Please enter a valid city and state in the shipping address This transaction cannot be processed Please enter a valid country code in the billing addre
115. ly one email this is the primary email Can also be a non primary email xs string ReceiptID Search by the PayPal Account Optional receipt ID xs string Transaction specific No TransactionID Search by the transaction ID ebl TransactionID Transaction specific s strin NOTE The returned results are from the merchant s transaction records Character length and limitations 19 single byte characters maximum InvoiceID Search by invoice identification key as set by you forthe xs string Transaction specific No original transaction InvoiceID searches the records for items sold by the merchant not the items purchased NOTE No wildcards are allowed Character length and limitations 127 single byte characters maximum CardNumber Search by credit card number as set by you for the xs string Transaction specific No original transaction CardNumber searches the records for items sold by the merchant not the items purchased NOTE No wildcards are allowed Character length and limitations Must be at least 11 and no more than 25 single byte numeric characters maximum Special punctuation such as dashes or spaces is ignored 104 July 2006 Web Services API Reference TABLE 10 1 TransactionSearchRequest Fields TransactionSearch API TransactionSearchRequest Element PayerName AuctionItem Number Transaction Class Amount CurrencyCode Description Search by the buyer s name Salutation 20 si
116. most important of these additional elements are as follows e ShortMessage e LongMessage e ErrorCode For a description of the contents of these elements see Appendix A Error Codes and Messages for PayPal APIs The following example shows the error response if your API username and password do not match a legitimate API username and password on file with PayPal EXAMPLE 2 1 Example of SOAP Error Response Bad Username or Password lt xml version 1 0 encoding UTF 8 gt lt SOAP ENV Envelope details not shown lt SOAP ENV Header gt details not shown SOAP ENV Header gt lt SOAP ENV Body id 0 gt I Web Services API Reference July 2006 29 30 PayPal Web Services Architecture PayPal Web Services API Definitions lt GetTransactionDetailsResponse xmlns urn ebay api PayPalAPI Timestamp xmlns urn ebay apis eBLBaseComponents gt 2005 02 09T21 51 26Z lt Timestamp gt lt Ack xmlns urn ebay apis eBLBaseComponents gt Failure lt Ack gt Errors xmlns urn ebay apis eBLBaseComponents xsi type ebl ErrorType gt lt ShortMessage xsi type xs string gt Authentication Authorization Failed lt ShortMessage gt lt LongMessage xsi type xs string gt Username Password is incorrect lt LongMessage gt lt ErrorCode xsi type xs token gt 10002 lt ErrorCode gt lt SeverityCode xmlns urn ebay apis eBLBaseComponents gt Error lt S
117. n MassPayItem MassPayItem Details of each payment ebl MassPayItem See Table 8 3 Yes T NOTE A single MassPayRequest can include up to 250 RE MassPayltems TABLE 8 2 ReceiverlnfoCodeType Enumeration Element Description Required EmailAddress Email address of recipient on file with PayPal No Character length and limitations 12 single byte alphanumeric characters UserID Unique PayPal customer account number No Character length and limitations 6 single byte characters maximum 98 July 2006 Web Services API Reference TABLE 8 3 MassPayltemType Fields MassPay API MassPayRequest Element ReceiverEmail ReceiverID Amount Uniqueld Note Description Email address of recipient IMPORTANT You must specify either Receiver Email ReceiverID but you must not mix Re ceiverEmail and ReceiverID in the group of MassPayltems Use only one or the other but not both in a single request Character length and limitations 127 single byte characters maximum Unique PayPal customer account number This value corresponds to the value of PayerID returned by GetTransactionDetails IMPORTANT You must specify either Receiver Email ReceiverID but you must not mix Re ceiverEmail and ReceiverID in the group of MassPayltems Use only one or the other but not both in a single request Character length and limitations 17 single byte characters maximum Payment amount NOTE Yo
118. n cannot be processed This transaction cannot be processed This transaction cannot be processed The transaction cannot be processed due to an invalid address This transaction cannot be processed Please enter a valid credit card number and type This transaction cannot be processed Please enter a valid email address This transaction cannot be processed This transaction cannot be processed Corrective Action The credit card entered is invalid The credit card entered is currently restricted by PayPal Contact PayPal for more information The credit card entered is invalid 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 The transaction was declined by the country filter managed by the merchant To accept this transaction change your risk settings on PayPal The transaction was declined by the maximum amount filter managed by the merchant To accept this transaction change your risk settings on PayPal The transaction was declined by PayPal 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 Contact PayPal for more information The email address provided by the buyer 1s in an invalid format The tr
119. ngle byte character limit FirstName 25 single byte character limit MiddleName 25 single byte character limit LastName 25 single byte character limit Suffix 12 single byte character limit Search by auction item number of the purchased goods Search by classification of transaction NOTE Some kinds of possible classes of transactions are not searchable with TransactionSearchRequest You cannot search for bank transfer withdrawals for example All all transaction classifications Sent only payments sent Received only payments received MassPay only mass payments MoneyRequest only money requests FundsAdded only funds added to balance FundsWithdrawn only funds withdrawn from balance Referral only transactions involving referrals Fee only transactions involving fees Subscription only transactions involving subscriptions Dividend only transactions involving dividends Billpay only transactions involving BillPay Transactions Refund only transactions involving funds CurrencyConversions only transactions involving currency conversions BalanceTransfer only transactions involving balance transfers Reversal only transactions involving BillPay reversals Shipping only transactions involving UPS shipping fees BalanceAffecting only transactions that affect the account balance ECheck only transactions involving eCheck Search by transaction amount NOTE You must set the currency ID attribute to one of the three c
120. ns 127 single byte characters FirstName Payer s first name ns PersonName See description Yes Character length and limitations 25 single byte Type characters LastName Payer s last name ns PersonName See description Yes Character length and limitations 25 single byte characters Type July 2006 Web Services API Reference TABLE 5 7 CardOwner Fields Direct Payment API DoDirectPaymentRequest Allowable Required Element Description DataType Values Address Payer s billing address information ns AddressType See Table 5 8 on Yes page 61 TABLE 5 8 CardOwner AddressType Fields Allowable Required Element Description DataType Values Streetl First street address xs string See description Yes Character length and limitations 100 single byte characters Street2 Second street address xs string See description No Character length and limitations 100 single byte characters CityName Name of city xs string See description Yes Character length and limitations 40 single byte characters StateOr State or province xs string See description Yes Character length and limitations 40 single byte characters Country Country code ebl CountryCode See Appendix 1 Yes Character length and limitations Two single byte idi characters re PostalCode U S Zip code or other country specific postal code xs string See description Yes Character length and limitations 20 single
121. number Internal Error Internal Error ButtonSource value truncated Transaction refused because of an invalid argument See additionalerror messages for details Account locked Transaction refused because of an invalid argument See additionalerror messages for details Long Message The transaction failed as a result of an invalid credit card number Check the number or attempt with another card Internal Error The transaction could not be loaded The transaction could not be loaded The masspay receiver type is not a recognizable type The user account is locked The number of input records is greater than maximum allowed 138 July 2006 Error Codes and Messages for All PayPal APIs MassPay API Errors TABLE A 8 MassPay API Errors Error Code 10004 10004 10004 10004 Short Message Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additional error messages for details Long Message The number of input records is less than or equal to zero The note string length exceeds the maximum limit of 4000 characters The amount is missing The currency is missing
122. numeric single byte characters The number of payment installments that will occur at the regular rate Character length and limitations no limit Indicates whether reattempts should occur upon payment failures Indicates whether regular rate recurs 1 Yes The amount subscriber is to be charged in one payment Character length and limitations no limit The period of time that the subscriber will be charged Character length and limitations no limit Includes the following elements Customer s auction ID Auction s close date Counter used for multi item auction payments Data Type and Possible Values ns OptionType name xs string value xs string Subscription InfoType xs string xs dateTime xs dateTime xs dateTime xs string xs string xs string xs string xs string eb BasicAmount Type xs string ebl AuctionInfo Type xs string xs string xs string July 2006 Web Services API Reference MassPay API The MassPay API is the programmatic counterpart to the Mass Payment feature available through the PayPal website You can include up to 250 payments per MassPayRequest You must have a PayPal balance in each currency in which you want to make a payment and have sufficient funds to cover the entire Mass Payment amount and fee You cannot mix currencies in the same MassPayRequest a separate request is required for each currency The posting of payment transactions to individ
123. oCapture DoReauthorization DoAuthorization DoCapture DoReauthorization DoCapture DoCapture DoVoid DoReauthorization DoReauthorization DoReauthorization DoAuthorization DoCapture DoReauthorization DoVoid DoCapture Correcting This Error Reattempt the request with a lower amount Contact PayPal Customer Service Close the order Ensure that the currencies are the same and retry the request Void the authorization Capture the reauthorization Capture or close the authorization Capture the authorization ro reauthorize outside of honor period Close the orde or authorizationr Check the length of the invoice ID and reattempt the request July 2006 Error Codes and Messages for All PayPal APIs Authorization amp Capture API Errors TABLE A 2 Authorization amp Capture API Error Messages Error Short Returned By API Code Message Long Message Call Correcting This Error 10620 Order has Order has already been DoAuthorization Close this order already been voided expired or DoCapture voided expired completed DoVoid or completed 10621 Order has Order has expired DoAuthorization Close this order expired DoCapture Do Void 10622 Order is Order is voided DoAuthorization Close this order voided DoCapture DoVoid 10623 Maximum Maximum number of DoAuthorization Capture this order number of authorization allowed for the DoCapture authorization order is reached DoRea
124. ong Message Correcting This Error You do not have permissions to make this API call You do not have a verified ACH This error can be caused by insufficient funds in your PayPal balance to cover the amount of the refund and either your not having yet verified the bank account associated with your PayPal account or your not having any bank account associated with your PayPal account at all Ensure that you have sufficient funds in your PayPal balance and that you have verified the associated bank account The partial refund amount must be less than or equal to the original transaction amount The partial refund amount must be less than or equal to the remaining amount The partial refund amount is not valid Because a complaint case exists on this transaction only a refund of the full or full remaining amount of the transaction can be issued You are over the time limit to perform a refund on this transaction Can not do a full refund after a partial refund Account is locked or inactive The partial refund must be the same currency as the original transaction This transaction has already been fully refunded Account is restricted You can not refund this type of transaction July 2006 145 Error Codes and Messages for All PayPal APIs TransactionSearch API Errors TABLE A 9 RefundTransaction API Errors Error Short Code Message Long Message Correcting This Error 10009 Transaction You can not do a part
125. page 63 CVV2Code Result of the CVV2 check by PayPal xs string See Table 5 11 CVV2 Response Codes on page 63 July 2006 Web Services API Reference TABLE 5 10 AVS Response Codes Direct Payment API DoDirectPaymentResponse AVS Code Meaning A Address B International A International International X Not allowed for MOTO Internet Phone transactions F UK specific X G Global Unavailable I International Unavailable No Postal International Z Retry Service not Supported Unavailable Whole ZIP Exact match Yes NK x 02 TD ZIP Error others 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 5 11 CVV2 Response Codes CVV2 Code Meaning M Match N No match Matched Details CVV2 None Web Services API Reference July 2006 63 SI Direct Payment DoDirectPaymentResponse TABLE 5 11 CVV2 Response Codes CVV2 Code Meaning Matched Details P Not Processed Not applicable S Service not Supported Not applicable U Unavailable Not applicable X No response Not app
126. pending for a reason other than those listed above For more information contact PayPal Customer Service Possible Values none address echeck inti multi currency verify other July 2006 Web Services API Reference Authorization amp Capture Bd DoAuthorization DoAuthorization 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 With the DoExpressCheckout PaymentRequest or DoDirectPaymentRequest PaymentAction element set to Order e 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 4 2 DoAuthorization Types Request Response DoAuthorizationRequestType DoAuthorizationResponseT ype TransactionID TransactionID TransactionEntity Amount Amount TransactionEntityType None Auth Reauth Order P
127. processes the request and generates the response Data Type XS XS ns token XS 5 5 5 token string ErrorType string string string Possible Values Success Failure SuccessWithWarning FailureWithWarning CustomCode Transaction specific Transaction specific 1 0 Web Services API Reference July 2006 37 m Core eBL Request Response Structures AbstractResponse Type 38 July 2006 Web Services API Reference Authorization amp Capture API The Authorization amp Capture API consists of individual requests and responses as shown below TABLE 4 1 Authorization amp Capture API Names Purposes and Types of Authorization Used With Type API Purpose of Authorization 1 DoCapture Settle an order or previously authorized transaction Order and Basic and obtain payment for either the complete amount or any portion of it 2 DoAuthorization Authorize an order that can be fulfilled over 29 Order only days 3 DoVoid Void an original authorization or order Order and Basic 4 DoReauthorization _ Reauthorize a previously authorized transaction 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 up to 11596 of the originally authorized amount not to exceed an increase of 75 USD Web Services API Reference
128. rName Elements 76 Table 6 8 Response AddressType Fields 76 Table 6 9 DoExpressCheckoutPaymentRequest Fields 79 Table 6 10 Request PaymentDetailsType Fields 80 Table 6 11 Request ShipToAddress AddressType Fields 82 Table 6 12 Request PaymentDetailsltemType Fields 83 Table 6 13 DoExpressCheckoutPaymentResponse Fields 84 Table 6 14 Response PaymentlnfoType Elements 84 Table 7 1 GetTransactionDetailsRequest Fields 88 Table 7 2 GetTransactionDetailsResponse Fields 88 Table 8 1 MassPayRequestType Fields 98 Table 8 2 ReceiverlnfoCodeType Enumeration 98 Table 8 3 MassPayltemTypeFields 99 Table 9 1 RefundTransactionRequest 102 Table 9 2 RefundTransactionResponse Fields 102 Table 10 1 TransactionSearchRequest Fields 104 Table 10 2 PaymentTransactions 106 Table A 1 General 109 Table A 2 Authorization amp Capture API Error Messages 110 Table A 3 Direct Payment Errors 114 Table 4 SetExpressCheckout API Errors 123 Table A 5 GetExpressCheckoutDetails Errors
129. rd 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 Details about the owner of the credit card ns PayerInfoType See Table 5 7 on page 60 Month that Switch or Solo card was issued xs int See description Character length two digit zero filled 1f necessary Year that Switch or Solo card was issued xs int See description Character length four digits Issue number of Switch or Solo card xs int See description Character length two numeric digits maximum Required 2 No See note in description Yes TABLE 5 3 Request PaymentDetails Type Fields Element OrderTotal ItemTotal Description Data Type Allowable Values Total of order including shipping handling and ebl BasicAmount See description tax Type 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 Sum of cost of all items in this order ebl BasicAmount See description Character length
130. rency decimal separator must be a period and the thousands separator must be a comma Equivalent to nine characters maximum for USD 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 Description of items the customer is purchasing Character length and limitations 127 single byte alphanumeric characters A free form field for your own use Character length and limitations 256 single byte alphanumeric characters Your own invoice or tracking number Character length and limitations 127 single byte alphanumeric characters An identification code for use by third party applications to identify transactions Character length and limitations 32 single byte alphanumeric characters Your URL for receiving Instant Payment Notification IPN about this transaction NoTE If you do not specify NotifyuRt 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 Allowable Data Type Values ebl BasicAmount See description Type e
131. rror with this transaction Please enter your five digit postal code in the billing address Corrective Action There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s 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 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 prob
132. rted currency Buyer cannot pay Auth amp Capture unavailable Funding source missing Invalid transactionID Long Message Authorization is voided Authorization has expired Authorization has already been completed The buyer account is restricted Authorization transaction cannot be unilateral It must include both buyer and seller to make an auth Currency is not supported Transaction rejected please contact the buyer Authorization amp Capture feature unavailable The funding source is missing Transaction id is invalid Returned By API Call DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoAuthorization DoCapture DoAuthorization DoCapture DoReauthorization DoAuthorization DoCapture DoReauthorization DoVoid DoAuthorization DoCapture DoReauthorization DoAuthorization DoCapture DoReauthorization DoVoid Correcting This Error Close the order or authorization Close the order or authorization Close the order or authorization Contact the buyer Review the order to ensure customer and seller are both PayPal members Retry the request with a PayPal supported currency Contact the buyer Contact PayPal Customer Service Contact the buyer Check the
133. s ses 39 40 Diagram of DoCapture 40 DoCaptureRequest 41 DoCaptureResponse 42 DoAuthorization 55525445425 ORO ORC Rem RO 45 Diagram of DoAuthorization Types 45 DoAuthorizationRequest 46 DoAuthorizationResponse 46 xe EEE NUR Rue dal POE wes 47 Diagram of DoVoid 47 DoVoidRequest 48 DoVoidResponse 48 DoReauthorization c egre e aioe a e p 5 a 49 Diagram of DoReauthorization 49 DoReauthorizationRequest 50 DoReauthorizationResponse 50 Chapter 5 Direct Payment 51 Diagram of DoDirectPayment 51 52 mI qM 52 62 4 July 2006 Web Services API Reference Contents E 25 ee a es ae et 62 Chap
134. saction specific Transaction specific Transaction specific Web Services API Reference July 2006 107 x TransactionSearch TransactionSearchResponse 108 July 2006 Web Services API Reference Error Codes and Messages for All PayPal APIs General API Errors TABLE A 1 General API Errors Short Error Code Message Long Message Correcting This Error 10002 Authentication Username Password is incorrect This error can be caused by Authorization an incorrect API username Failed an incorrect API password or an invalid API signature Make sure that all three of these values are correct For your security PayPal does not report exactly which of these three values might be in error 10002 Authentication You do not have permissions to make this API Authorization call Failed 10002 Authentication Account is locked or inactive Authorization Failed 10002 Internal Error Internal Error 10002 Authentication Internal Error Authorization Failed 10002 Authentication Account is not verified Authorization Failed 10002 Authentication This call is not defined in the database Authorization Failed 10002 Authentication Token is not valid Authorization Failed July 2006 109 Error Codes and Messages for All PayPal APIs Authorization amp Capture API Errors TABLE A 1 General API Errors Error Code 10002 10002 10002 10002 10002 Short Message Restricted account Authentication
135. sages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Long Message End date is invalid Currency is not supported Transaction class is not supported Receipt id is not valid Payer email is invalid Auction item id is not valid Receiver email is invalid You can not search for a transaction id and a receipt id Receiver can only be specified for payments you ve received The transaction id is not valid July 2006 147 148 Error Codes and Messages for All PayPal APIs TransactionSearch API Errors TABLE A 10 TransactionSearch API Errors Error Code 10007 10007 11002 Short Message Permission denied Permission denied Search warning Long Message You do not have permissions to search for this transaction You do not have permissions to make this API cal
136. seDetailsT ype Token Token PayerInfo Custom InvoicelD ContactPhone PayerInfoType Payer PayerID PayerStatus PayerName PayerCountry PayerBusiness Address PersonNameType Salutation FirstName MiddleName LastName Suffix AddressType AddressStatus Name Street I Street2 CityName StateOrProvince PostalCode Country Web Services API Reference July 2006 73 74 Express Checkout API GetExpressCheckoutDetails GetExpressCheckoutDetailsRequest Fields TABLE 6 4 GetExpressCheckoutDetailsRequest Fields Obtain details about a payment to be processed by PayPal Express Checkout Element Token Description Data Type A timestamped token the value of which was xs string returned by SetExpressCheckoutResponse Character length and limitations 20 single byte characters Allowable Required Values Anunexpiredtoken Yes GetExpressCheckoutDetailsResponse Response to GetExpressCheckoutDetailsRequest Fields TABLE 6 5 GetExpressCheckoutDetailsResponse Fields Element Token PayerInfo Custom InvoiceID Description Data Type The timestamped token value that was returned by xs string SetExpressCheckoutResponse and passed on GetExpressCheckoutDetailsRequest Character length and limitations 20 single byte characters Information about the payer ebl PayerInfoType A free form field for your own use as set by you in xs string the custom e
137. ss This transaction cannot be processed Please enter a valid country code in the shipping address This transaction cannot be processed Please use a valid country on the billing address This transaction cannot be processed This transaction cannot be processed without a Credit Card Verification number There s an error with this transaction Please enter a valid state in the shipping address Corrective Action There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid The merchant entered an IP address that was in an invalid
138. sspay server is incorrect Please make sure that you are using a correctly formatted input The masspay input file includes invalid Email Internal Error The account does not have sufficient funds to do this masspay The masspay input file includes invalid UserID 142 July 2006 Error Codes and Messages for All PayPal APIs RefundTransaction API Errors RefundTransaction API Errors TABLE A 9 RefundTransaction API Errors Error Code 10001 10001 10001 10001 10004 10004 10004 Short Message Internal Error Internal Error ButtonSource value truncated Internal Error Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Long Message Correcting This Error Internal Error Warning an internal error has occurred The transaction id may not be correct The transaction could not be loaded Internal Error The partial refund amount must be a positive amount You can not specify a partial amount with a full refund A transaction id is required July 2006 143 144 Error Codes and Messages for All PayPal APIs RefundTransaction API Errors TABLE A 9 RefundTransaction API Errors Error Code 10004 10004 10004 10004
139. t with PayPal Payment Authorization amp Capture Request will bea e Sale indicates that this is a final sale for which Authorization you are requesting payment IMPORTANT You cannot set PaymentAction to NG Sale 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 PayerID Encrypted PayPal customer account identification eb1 UserIDType See description Yes number as returned by GetExpressCheckoutDetailsResponse Character length and limitations 127 single byte characters Web Services API Reference July 2006 79 80 Express Checkout API DoExpressCheckoutPayment TABLE 6 9 DoExpressCheckoutPaymentRequest Fields Allowable Required Element Description Data Type Values PaymentDetails Information about the payment ebl PaymentDetails See Table 6 10 Yes Type page 80 TABLE 6 10 Request PaymentDetailsType Fields Allowable Required Element Description Data Type Values OrderTotal Total of order including shipping handling and ebl BasicAmount See description Yes tax Type 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 curren
140. ted account Unconfirmed email Limit Exceeded Limit Exceeded Receive only account Masspay server configuration error Long Message The unique id string contains a space as a character The transaction id is not valid You do not have permissions to make this API call The user is not allowed to send money through Mass Pay Account is restricted The user account has unconfirmed email The user account needs to have its sending limit removed in order to make a mass payment The user s international account needs to have its sending limit removed in order to make a mass payment The user account is receive only and therefore cannot send payments out There is some configuration error July 2006 141 MassPay API Errors Error Codes and Messages for All PayPal APIs TABLE A 8 MassPay API Errors Error Code 10309 10310 10311 10312 10313 10314 10317 10320 10321 10327 Short Message Masspay server unavailable Unable to create payment Unable to submit payment Masspay server error Masspay Invalid Data Masspay input parse error Masspay Invalid Email Internal Error Insufficient funds Masspay Invalid UserID Long Message The mass pay server is unavailable Unable to create payments for masspay Unable to submit payments for masspay The masspay server has reported errors The masspay input file includes invalid data The input to the ma
141. ter 6 Express Checkout 4 65 55 66 Diagram of Set ExpressCheckout Types 66 55 1 67 SetExpressCheckoutResponse 72 55 73 Diagram of GetExpressCheckoutDetails 73 GetExpressCheckoutDetailsRequest 74 GetExpressCheckoutDetailsResponse 74 DoExpressCheckoutPayment 77 Diagram of DoExpressCheckoutPayment Types 77 DoExpressCheckoutPaymentRequest 79 DoExpressCheckoutPaymentResponse 83 Chapter 7 GetTransactionDetails API 87 Diagram of GetTransactionDetails Types 87 GetTransactionDetailsRequest 88 a ccc c 88 GetTransactionDetailsResponse 88 Fields ss udo e bdo deh c bed s Reeve de es 88 Chapter 8 5 1 97 Instant Payment 97 Diagram of MassPay 97 MassPayRequest 98 ICIS ag TE
142. ters Country Country code ebl CountryCode Character limit Two single byte characters Type xs string Allowable Values See description See description See description See description See description See Appendix B Required Yes Yes SetExpressCheckoutResponse Response to SetExpressCheckoutRequest Fields TABLE 6 3 SetExpressCheckoutResponse Fields Element Description Data Type Token A timestamped token by which you identify to xs string 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 Value See description July 2006 Web Services API Reference Express Checkout API GetExpressCheckoutDetails GetExpressCheckoutDetails 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 Request Response GetExpressCheckoutDetailsRequest Type GetExpressCheckoutDetailsRespon
143. th SetExpressCheckout at Integration Point 1 and switch PaymentAction to Sale with DoExpressCheckoutPayment at Integration Point 3 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 July 2006 TABLE A 6 DoExpressCheckoutPayment API Errors Error Codes and Messages for All PayPal APIs Express Checkout Errors Error Code 10432 10433 10434 10435 10441 10442 Short Message Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details Transaction refused because of an invalid argument See additionalerror messages for details ButtonSource value truncated Long Message Invoice ID value exceeds maximum allowable length Value of OrderDescription element has been truncated Value of Custom element has been truncated The customer h
144. th doc literal a single service interface call passes an XML document in the request to the PayPal API server which responds with an XML document instance SOAP Request Envelope The following diagram illustrates the contents of a PayPal SOAP request envelope PayPal APIs are based on two core structures Abstract RequestType and AbstractResponseType FIGURE 2 2 Diagram of SOAP Request Envelope SOAP Request Envelope eBL RequesterCredentials API user id Username API user password Password API Signature Signature Third party Authentication Subject eBL Payload elements specific to particular PayPal API Request Structure The following 1s an annotated description of the SOAP request structure required by the PayPal Web Services API 26 July 2006 Web Services API Reference EXAMPLE 2 1 General 1 lt xml v PayPal Web Services API Architecture SOAP Implementation Structure of PayPal API SOAP Request rsion 1 0 encoding UTF 8 2 SOAP ENV Envelope xmlns xsi http www w3 0rg 2001 XMLSchema instance xmlns SOAP ENC http schemas xmlsoap org soap encoding xmlns SOAP ENV http schemas xmlsoap org soap envelope SOAP ENV encodingStyle http schemas xmlsoap org soap encoding lt SOAP ENV Header gt 3 4 6 xmlns xsd http www w3 org 2001 XMLSchema 7 8 9 lt RequesterCredentials xmlns urn ebay ap
145. thorization can only be handled through the marketplace which created it It cannot directly be voided reauthorized or captured against Returned By API Call DoAuthorization DoCapture DoReauthorization DoVoid DoReauthorization DoAuthorization DoCapture Correcting This Error Retry the request at a later time Use DoAuthorization to authorize the an order Check the item amount to ensure that it is not zero or negative Direct Payments API Errors TABLE A 3 Direct Payment API Errors Error Code 10500 10501 10502 Short Message Invalid Configuration Invalid Configuration Invalid Data Long Message This transaction cannot be processed due to an invalid merchant configuration This transaction cannot be processed due to an invalid merchant configuration This transaction cannot be processed Please use a valid credit card Corrective Action Occurs when you have not agreed to the billing agreement Occurs when the billing agreement is disabled or inactive The credit card used is expired July 2006 Error Codes and Messages for All PayPal APIs TABLE A 3 Direct Payment API Errors Direct Payments Errors Error Code 10504 10505 10507 10508 10509 10510 10511 10512 10513 10519 10520 10521 10523 10525 10526 Short Message Invalid Data Gateway Decline Invalid Configuration Invalid Data
146. through the main PayPal website https www paypal com Typical applications include searching for transactions paying en masse and making refunds The API is based on open standards known collectively as Web Services which include the Simple Object Access Protocol SOAP Web Services Definition Language WSDL and the XML Schema Definition language XSD These standards are supported by a wide range of development tools on a variety of platforms Services Architecture Like many web services PayPal Web Services is a combination of client side and server side schemas hardware and software servers and core services FIGURE 2 1 PayPal Web Services High level Diagram PayPal Web Services API Servers Test api sandbox pbaypal com 2 0 api aa sandbox paypal com 2 0 Production api paypal com 2 0 api 3t paypal api aa paypal co api aa 3t paypal com 2 0 eet yn se Processing application between PayPal serviceand Core Services PayPal main Transaction Engine site it Business Logic Test www Sandbox paypal corm Production www Daypal com PayPal Main Interactive Site In an object oriented processing model the interface to SOAP requests responses is an object in your application s native programming language Your third party SOAP client generates Web Services Reference July 2006 PayPal Web Services API Architecture Services Arc
147. tomer guarantee A reversal has occurred on this transaction due to your customer triggering a money back guarantee buyer complaint A reversal has occurred on this transaction due to a complaint about the transaction from your customer refund A reversal has occurred on this transaction because you have given the customer a refund other A reversal has occurred on this transaction due to a reason not listed above Includes the following elements Invoice number you set in the original transaction Character length and limitations 127 single byte alphanumeric characters Custom field you set in the original transaction Character length and limitations 127 single byte alphanumeric characters Memo entered by your customer in PayPal Website Payments note field Character length and limitations 255 single byte alphanumeric characters Amount of tax charged on payment Item name set by you or entered by the customer If this was a shopping cart transaction PayPal appends the number of the item to the HTML item name variable For example item namel item name2 and so forth Character length and limitations 127 single byte alphanumeric characters Item number set by you If this was a shopping cart transaction PayPal appends the number of the item to the HTML item name variable For example item namel item name2 and so forth Character length and limitations 127 single byte alphanumeric characters
148. tp schemas xmlsoap org ws 2002 07 utility 10 xmlns saml urn oasis names tc SAML 1 0 assertion 11 xmins ds http www w3 org 2000 09 xmldsig 12 xmlns wsse http schemas xmlsoap org ws 2002 12 secext 13 xmlns ebl urn ebay apis eBLBaseComponents 14 xmlns ns urn ebay api PayPalAPI 15 lt SOAP ENV Header gt 16 Security xmlns http schemas xmlsoap org ws 2002 12 secext xsi type wsse SecurityType 17 lt RequesterCredentials xmlns urn ebay api PayPalAPI xsi type ebl CustomSecurityHeaderType 18 Credentials xmlns urn ebay apis eBLBaseComponents xsi type ebl UserIdPasswordType 19 lt RequesterCredentials gt 20 lt SOAP ENV Header gt 21 SOAP ENV Body id 0 22 specific name Response xmlns urn ebay api PayPalAPI 23 lt Timestamp gt dateTime_in_UTC GMT lt Timestamp gt 24 lt Ack xmlns urn ebay apis eBLBaseComponents gt Success lt Ack gt 25 Version xmlns urn ebay apis eBLBaseComponents gt serviceVersion lt Version gt 26 lt CorrelationId xmlns urn ebay apis eBLBaseComponents applicationCorrelation CorrelationID 27 Build xmlns urn ebay apis eBLBaseComponents api build number lt Build gt 28 elements for specific api response 29 data 30 elements for specific api response 31 specific api name Response 32 SOAP ENV Body 33 SOAP ENV Envelope 28 July 2006 Web Ser
149. transaction Please enter a valid address2 in the shipping address There s an error with this transaction Please enter a valid city in the shipping address There s an error with this transaction Please enter a valid state in the shipping address Corrective Action There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell yo
150. two digit month and four digit year 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 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 None this is a PayPal internal error The merchant entered a amount of zero The currency code entered 1s not supported July 2006 115 116 Error Codes and Messages for All PayPal APIs Direct Payments API Errors TABLE A 3 Direct Payment API Errors Error Code 10527 10534 10535 10536 10537 10538 10539 10540 10541 10542 10544 10545 Short Message Invalid Data Gateway Decline Gateway Decline Invalid Data Filter Decline Filter Decline Filter Decline Invalid Data Gateway Decline Invalid Data Gateway Decline Gateway Decline Long Message 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 This transaction cannot be processed Please enter a valid credit card number and type This transaction cannot be processed This transactio
151. u do not have your Payment Receiving Preferences set to automatically convert and accept this payment You must manually accept or deny this payment unilateral The payment is pending because it was made to an email address that is not yet registered or confirmed upgrade The payment is pending because it was made via credit card and you must upgrade your account to Business or Premier status in order to receive the funds upgrade can also mean that you have reached the monthly limit for transactions on your account 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 Data Type and Possible Values ebl PendingStatus CodeType xs token none authorization address echeck intl multi currency unilateral upgrade verify other 94 July 2006 Web Services API Reference TABLE 7 2 GetTransactionDetailsResponse Fields GetTransactionDetails API GetTransactionDetailsResponse Element Included Element ReasonCode PaymentItem Info InvoiceID Custom Memo PaymentItem SaleTax Name Number Quantity Amount Description The reason for a reversal if TransactionType is reversal none No reason code chargeback A reversal has occurred on this transaction due to a chargeback by your cus
152. u must set the currencyID attribute to one of the three character currency codes for any of the supported PayPal currencies See page 31 IMPORTANT You cannot mix currencies in a single MassPayRequest A single request must include items that are of the same currency Transaction specific identification number for tracking in an accounting system Character length and limitations 30 single byte characters No whitespace allowed Custom note for each recipient Character length and limitations 4 000 single byte alphanumeric characters Data Type ebl EmailAddress Type xs string ebl BasicAmount Type xs string xs string Possible Values Required See descirption No Transaction specific No Transaction specific Yes Transaction specific No Transaction specific No Web Services API Reference July 2006 99 p MassPay API MassPayResponse MassPayResponse Response to MassPayRequest Fields The elements returned are the same as for AbstractResponseType See page 36 For error codes and messages and their meanings see Appendix Error Codes and Messages for PayPal APIs 100 July 2006 Web Services API Reference RefundTransaction Use the RefundTransaction API to make either full or partial refunds Instant Payment Notification Use of the RefundTransaction API triggers the sending of an Instant Payment Notification email to the recipient of the refund Diagram of
153. u what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid There was a problem with a particular field in the address The long error message will tell you what field 1s invalid July 2006 119 120 Error Codes and Messages for All PayPal APIs Direct Payments API Errors TABLE A 3 Direct Payment API Errors Error Code 10724 10725 10726 10726 10727 10727 10728 10728 10729 10730 10731 10731 Short Message Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Invalid Data Long Message There s an error with this transaction Please enter your five digit postal code in the shipping address There s an error with this transaction Please enter a valid country in the shipping address There s an error with this transaction Please enter a complete shipping address There s an error with this transaction Please enter a complete shipping address There s an error with this transaction Please enter an address in the shipping address There s an error with this transaction Please enter an address1 in the shipping address There s an error with this transaction Please enter a city in the shipping address There s an error with this transaction Please enter a city
154. ual recipient accounts is not handled by the MassPay API but by a separate PayPal process Instant Payment Notification The MassPay API triggers the sending of an Instant Payment Notification email to the recipient of the funds Diagram of MassPay Types The following diagram represents the composition of the MassPayRequestType MassPayRequestItemType and MassPayResponseType elements FIGURE 8 1 MassPay Types Request Response MassPayRequestType EmailSubject MassPayResponse ReceiverType MassPayltem ReceiverInfoCodeType EmailAddress See UserlD AbstractResponseType MassPayltem up to 250 items MassPayltemRequestType ReceiverEmail ReceiverID Web Services API Reference July 2006 97 p MassPay API MassPayRequest MassPayRequest Process payments en masse to up to 250 different recipients Fields TABLE 8 1 MassPayRequestType Fields Element Description Data Type Possible Values Required EmailSubject Subject line of the email sent to all recipients This subject xs string See description No is not contained in the input file you must create it with your application Character length and limitations 255 single byte alphanumeric characters ReceiverType Indicates how you identify the recipients of payments in ebl ReceiverInfo See Table 8 2 No all MassPayItems either by EmailAddress CodeType ReceiverEmail in MassPayItem or by UserID xs token ReceiverID i
155. ues float not decimal e Date time values Coordinated Universal Time UTC GMT using ISO 8601 format and of type ns dateTime PayPal Supported Currencies The following currencies are supported by PayPal TABLE 2 7 PayPal Supported Currencies Currency Codes and Maximum Transaction Amounts Maximum Transaction Code Currency Amount AUD Australian Dollar 12 500 AUD CAD Canadian Dollar 12 500 CAD EUR Euro 8 000 EUR GBP Pound Sterling 5 500 GBP JPY Japanese Yen 1 000 000 JPY USD U S Dollar 10 000 USD Web Services API Reference July 2006 31 SI PayPal Web Services API Architecture PayPal Web Services API Definitions The core currency amount data type 1s derived from string and all currency amount elements have the following structure The currencyID attribute is required Amount currencyID currencyCode ns Basi cAmountType Amount The element name Amount is an example actual element names can vary depending on the specific API BasicAmountType has a data type of eb1 CurrencyCodeType which defines a large number of different currency codes However for your processing to succeed you must set currencyCode to one of the values from the first column of Table 2 7 PayPal Supported Currencies Currency Codes and Maximum Transaction Amounts on page 31 Some APIs support only a subset of these currencies API Overview By Business Function and Service Endpoint The PayPal Web Services API consists o
156. ult of your Maximum Amount Risk Control Settings Payment declined by your Risk Controls settings PayPal Risk Model July 2006 Error Codes and Messages for All PayPal APIs GetTransactionDetails API Errors TABLE A 6 DoExpressCheckoutPayment API Errors Error Code 10725 10727 10728 10729 10730 10731 10736 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 Correcting This Error There was an error in the Shipping Address Country field The field Shipping Address1 is required The field Shipping Address City is required The field Shipping Address State is required The field Shipping Address Postal Code is required The field Shipping Address Country is required A match of the Shipping Address City State and Postal Code failed GetTransactionDetails API Errors TABLE A 7 GetTransactionDetails API Errors Short Error Code Message Long Message 10001 Internal Error Internal Error July 2006 137 Error Codes and Messages for All PayPal APIs MassPay API Errors MassPay API Errors TABLE A 8 MassPay API Errors Error Code 10001 10001 10001 10001 10001 10002 10004 Short Message Invalid account
157. um for USD Description of items the customer is purchasing Character length and limitations 127 single byte alphanumeric characters A free form field for your own use such as a tracking number or other value you want PayPal to return on GetExpressCheckoutDetailsResponse and DoExpressCheckoutPaymentResponse Character length and limitations 256 single byte alphanumeric characters Your own unique invoice or tracking number PayPal returns this value to you on DoExpressCheckoutPaymentResponse Character length and limitations 127 single byte alphanumeric characters 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 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 Allowable Data Type Values cc BasicAmount See description Type xs string See description xs string See description xs string See description xs string See description xs string See description Required 2 No Yes Yes July 2006 Web Services API Reference Express Checkout API NEA SetExpressCheckout TABLE
158. uthorization Please contact Customer Service ReturnURL is missing CancelURL is missing July 2006 Error Codes and Messages for All PayPal APIs Express Checkout Errors TABLE A 4 SetExpressCheckout API Errors Error Code 10407 10409 10410 10411 10412 Short Message Transaction refused because of an invalid argument See additionalerror messages for details You re not authorized to access this info Invalid token This Express Checkout session has expired Duplicate invoice Long Message Invalid buyer email address BuyerEmail Express Checkout token was issued for a merchant account other than yours Invalid token This Express Checkout session has expired Token value is no longer valid Payment has already been made for this InvoicelD Correcting This Error 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
159. uthorization allowed for the DoVoid order is reached 10624 Duplicate Payment has already been DoAuthorization Review the invoice ID and invoice made for this InvoiceID reattempt the request 10625 Transaction The amount exceeds the DoAuthorization Reattempt the request with a refused maximum amount for a DoCapture lower amount because ofan single transaction invalid argument See additionalerror messages for details 10626 Risk Transaction refused due to DoAuthorization Contact the buyer risk model DoCapture DoReauthorization 10627 Transaction The invoice ID field is not DoAuthorization The Invoice ID field can only be refused supported for basic DoReauthorization used with DoCapture because ofan authorizations DoVoid invalid argument See additional error messages for details July 2006 113 114 Error Codes and Messages for All PayPal APIs Direct Payments API Errors TABLE A 2 Authorization amp Capture API Error Messages Error Code 10628 10629 10630 11094 Short Message This transaction cannot be processed at this time Please try again later Reauthorizatio n not allowed Item amount is invalid This authorization cannot be voided reauthorized or captured against Long Message This transaction cannot be processed at this time Please try again later Reauthorization is not allowed for this type of authorization Item amount is invalid This au
160. validity of the authorization ID and reattempt the request July 2006 111 112 Error Codes and Messages for All PayPal APIs Authorization amp Capture API Errors TABLE A 2 Authorization amp Capture API Error Messages Error Code 10610 10611 10612 10613 10614 10615 10616 10617 10618 10619 Short Message Amount limit exceeded Not enabled No more settlement Currency mismatch Cannot void reauth Cannot reauth reauth Maximum number of reauthorization allowed for the auth is reached Reauthorizatio n not allowed Transaction already voided or expired Invoice ID value exceeds maximum allowable length Long Message Amount specified exceeds allowable limit Authorization amp Capture feature is not enabled for the merchant Contact customer service Maxmimum number of allowable settlements has been reached No more settlement for the authorization Currency of capture must be the same as currency of authorization You can void only the original authorization not a reauthorization You can reauthorize only the original authorization not a reauthorization Maximum number of reauthorization allowed for the auth is reached Reauthorization is not allowed inside honor period Transaction has already been voided or expired Invoice ID value exceeds maximum allowable length Returned By API Call DoAuthorization D
161. vices API Reference PayPal Web Services API Architecture SOAP Implementation TABLE 2 6 Annotation of Generic SOAP Response Lines Comment 22 and 31 The specific api name Response start and end elements 23 Each API response contains a timestamp with its date and time in UTC GMT 24 The lt Ack gt element contains the string Success after the corresponding request has been successfully processed For a complete list of possible returned strings see AbstractResponseType on page 36 In the case of errors Ack is set to a value other than Success and the response body contains an Errors element with information to help you troubleshoot the cause of the error See Error Responses on page 29 26 The CorrelationID element contains information about the PayPal application that processed the request 27 through different PayPal APIs return different structures depending on their response definitions For 30 detailed information see the description of the individual APIs NOTE Because a field is defined in the formal structure of an API response does not mean that that field is necessarily returned Data are returned in a response only if PayPal has recorded data that corresponds to the field Error Responses If a request is malformed or some other error the body of the SOAP response contains an Errors element with other elements that can help you troubleshoot the cause of the error The
162. xt 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 Documentation Problems If you discover any errors in or have any problems with this documentation please email us by following the instructions below Describe the error or problem as completely as possible and give us the document title the date of the document located at the foot of every page and the page number or page range To contact Developer Technical Support about documentation problems 14 July 2006 Web Services API Reference Revision History 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 Web Services API Reference TABLE 1 1 Revision History Date Description July 2006 CardNumber field added to TransactionSearch API Significantly improved error messages for Direct Payment API Minor change to one Mass Pay API error message March 2006 Updated for new API credential API signatures New SOAP service endpoint for signatures Miscellaneous minor corrections throughout January 2006 Additional error messages for Authorization amp Capture APIs and Express Checkout APIs December 2005

PayPal Web Services API - 2006 Reference Manual

Contents

Download Pdf Manuals

Related Search

Related Contents