Home

PayPal Name-Value Pair API - 2007 Reference Manual

1. TAXAMT Amount of tax for transaction EXCHANGERATE Exchange rate for transaction PAYMENTSTATUS Status of the payment The status of the payment e None No status e Canceled Reversal This means a reversal has been canceled For example you won a dispute with the customer and the funds for the transaction that was reversed have been returned to you e Completed The payment has been completed and the funds have been added successfully to your account balance e Denied You denied the payment This happens only if the payment was previously pending because of possible reasons described for the PendingReason element e Expired the authorization period for this payment has been reached e Failed The payment has failed This happens only if the payment was made from your customer s bank account e Pending The payment is pending See the PendingReason field for more information e Refunded You refunded the payment Reversed A payment was reversed due to a chargeback or other type of reversal The funds have been removed from your account balance and returned to the buyer The reason for the reversal is specified in the ReasonCode element e Processed A payment has been accepted e Voided An authorization for this transaction has been voided Name Value Pair API Developer Guide and Reference April 2007 57 EA NVP API Method and Field Reference GetTransactionDetails TABLE A 15 GetTransac
2. The GetExpressCheckoutDetails method returns information about the customer including name and address stored on PayPal You must always include the following parameters in GetExpressCheckoutDetails e TOKEN use the value from SetExpressCheckout response The response contains this TOKEN and customer details EXAMPLE 2 2 Getting Payer Details requiredSecurityParameters METHOD GetExpressCheckoutDetails Request TOKEN EC 3DJ78083ES565113B successResponseFields sTOKEN EC 3DJ7 8083ES565113B amp EMAIL abcdef anyemail com amp PAYERID 95HR9CM6D5 602 K PAYERSTATUS veri fied amp FIRSTNAME John amp LASTNAME Smith COUNTRYCODE US amp SHIPTONAME John Smith amp SHIPTOSTREET 144 MaintSt K SHIPTOCITY San Jose amp SHI PTOSTATE CA amp SHI PTOCOUNTRYCODE US amp SHIPTOZIP 992218ADDRESSID PayPalg Response ADDRESSSTATUS Confirmed Make sure TOKEN matches the value in SetExpressCheckout response Save PAYERID for use on the next call 4 Making a Sale Using DoExpressCheckoutPayment Request to obtain payment with PayPal Express Checkout using DoExpressCheckoutPayment request By default you make a final sale with DoExpressCheckout Payment request You must always include the following parameters in DoExpressCheckoutPayment request e TOR GI N use the value from GetExpressCheckoutDetails response
3. rn 101 Download and Unzip the Samples 0 e e 101 Installing the Samples e 101 Running the Samples es 101 Name Value Pair API Developer Guide and Reference April 2007 5 ee Contents Appendix D The JavaSDK eee 103 Installing the Java SDK 0 o me 103 Supported Standards ev rv ranks 103 Recommended Hardware Configuration 22 2 aar a e 2 104 Download and Unzip the SDK 2 022000 104 Post installation Set up 1 104 Complete SDK and API Class Documentation 2 22 arr a kr nr 050s 105 SPK Logging r s der ap seer a ee e e Eye E ds as dar a 105 PHONES pet ag ss De eG ee KR AG EE AE GE A A h 106 Overview to Profile related Classes 2 2 2 2 ee 106 Sample Applications 2 a nn 107 Sample API User with API Signature aoaaa aa ee 108 Sample API User with API Certificate 222 vr vr 0 0002 108 Appendix E The ASP NET SDK 109 Installing the ASP NET SDK L 2 Lara vara rar kaka ren 109 Supported Standards o oaoa a a a a a 109 Downloading and Installing the SDK a 110 Post installation Set up a 110 Optional Custom Configurations in Web config oa a a 111 SDK Logging 2 aa seks daa aa ra 111 Enabling Proxy Support arna 113 Uninstalling the SDK cuc
4. LOCALECODE Locale of pages displayed by PayPal during Express Checkout No Character length and limitations Any two character country code The following two character country codes are supported by PayPal AU DE FR IT GB ES US Any other value will default to US NOTE For the list of country codes see Appendix F Country Codes PAGESTYLE Sets the Custom Payment Page Style for payment pages associated No with this button link This value corresponds to the HTML variable page_style for customizing payment pages The value is the same as the Page Style Name you chose when adding or editing the page style from the Profile subtab of the My Account tab of your PayPal account Character length and limitations 30 single byte alphabetic characters HDRIMG A URL for the image you want to appear at the top left of the No 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 HDRBORDERCOLOR Sets the border color around the header of the payment page The No 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 HDRBACKCOLOR Sets the background color for the header of the payment page No Character length and limitation Six charact
5. SDK Logging The PayPal SDK uses log4j public domain logging software For complete information see the documentation at http logging apache org log4j docs Setting Log Levels Set the value of the level element in SDK root lib log4j properties TABLE D 4 SDK Logging Levels Level Description ALL Same as DEBUG ERROR Log only severe errors INFO Date time of API operation operation name elapsed time success or failure indication DEBUG Full text of requests and responses and other debugging messages Because DEBUG logging can degrade the performance of the SDK be careful about using it for day to day operation NOTE Because requests and responses are asynchronous the recording of requests and responses might appear out of sequence in the log file Logfile Backup The default size ofthe SDK log is 10MB You can set this size larger or smaller with the value of param name MaxFileSize in log4j properties When the log file reaches its maximum size a backup file is created and a new logfile begins Name Value Pair API Developer Guide and Reference April 2007 105 el The Java SDK Profiles Profiles Before the SDK can be used it must know the profile of the user accessing its services A profile is a collection of information about a merchant or developer who uses the PayPal SDK An API profile is associated with API Services and includes e A PayPal API username and password e Ifyou ar
6. e BANKTXNPENDINGURL EXAMPLE 2 1 Starting the Checkout requiredSecurityParameters METHOD SetExpressCheckoutsAMT 10 006 RETURNURL https ww anycompany com orderprocessing orderreview htmlg Request CANCELURL https ww anycompany com orderprocessing shippinginfo html Response successResponseFields sTOKEN EC 3DJ78083ES565113B Note Because we do not specify a value for PAYMENTACTION this parameter defaults to Sale Save TOKEN for use on the remaining Express Checkout calls 2 Redirecting the Customer s Browser to PayPal Login Page After you receive a successful response from SetExpressCheckout add the TOKEN from SetExpressCheckout response as a name value pair to the following URL and redirect your customer s browser to it https www paypal com cgi bin webscr cmd express checkout token value from SetExpressCheckoutResponse For redirecting the customer s browser to the PayPal login page PayPal recommends that you use the HTTPS response 302 Object Moved with the URL above as the value of the Location header in the HTTPS response Ensure that you use an SSL enabled server to prevent browser warnings about a mix of secure and insecure graphics 18 April 2007 Name Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout Basic Checkout with PayPal Moe 3 Getting Payer Details Using GetExpressCheckoutDetails
7. e Name value pairs are separated by an ampersand 4 For example FIRSTNAME Robert MI DDLENAME Herbert amp LASTNAME Moore e The NVP string is URL encoded 12 April 2007 Name Value Pair API Developer Guide and Reference Overview Technical Details ul URL Encoding The request and response are URL encoded URL encoding ensures that you can transmit special characters characters that are not allowed in a URL and characters that have special meaning in a URL such as the equal sign and ampersand For example the following NVP string NAME Robert Moore amp COMPANY R H Moore amp Associates is URL coded as follows NAME Robert Moore amp COMPANY R 2E H 2E Moore 26 Associates Use the following methods to URL encode or URL decode your NVP strings TABLE 1 2 URL Encoding Methods Language Method ASP NET Encode System Web HttpUtility UrlEncode buffer Encoding Default Decode System Web HttpUtility UrlDecode buffer Encoding Default Classic Encode Server URLEncode ASP Decode No built in function Several implementation examples are available on the Internet Java Encode java net URLEncoder encode Decode java net URLDecoder decod PHP Encode urlencode Decode urldecode ColdFusion Encode URLEncodedFormatstring charset E Decode URLDecodeurlEncodedString charset Name Value Pair API Developer Guide
8. 63 VERSION 2 3 14 Voided 57 W Web config 111 112 paypal tag 111 Website Payments Standard Integration Guide 106 114 WinHttpCertCfg exe 116 WinHttpPCertCfg exe 116 Y Yen 36 Z Zloty 36 Name Value Pair API Developer Guide and Reference March 2007 127
9. API signature A IzJhZZjhg29XQ02qnhapuwxIDzyAZQ92FRP5dq9BzVesOkzbdUONZmOU IMPORTANT You must protect the API signature values in your implementation Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it The sample code does not store these values securely The sample code should never be used in production Name Value Pair API Developer Guide and Reference April 2007 115 el The ASP NET SDK Sample API User with API Certificate Sample API User with API Certificate The samples come with an API digital certificate for use with the SDK and the PayPal Sandbox This certificate belongs to the following user TABLE E 8 Details of the SDK Sample API Certificate Location of Certificate SDK_root samples Certs sdk seller p12 API Username sdk seller apil sdk com API Password 12345678 PKCS12 Passphrase password IMPORTANT You must protect the API Certificate values in your implementation Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it The sample code does not store these values securely The sample code should never be used in production Installing the Samples in IIS NoTE Be sure you are logged in as an admini
10. Accepting PayPal in Express Checkout Including Subtotals Using DoExpressCheckoutPayment 2 Here are examples of ITEMAMT and TAXAMT L AMT1 L QTY1 L AMT2 ITEMAMT L AMTO L QTYO L TAXAMT1 L QTY1 L TAXAMT2 TAXAMT L TAXAMTO L QTYO Nore If the line item details do not add up to ITEMAMT or TAXAMT the line item details are discarded and the transaction is processed using the values of ITEMAMT or TAXAMT The ACK value in the response is set to SuccessWithWarning Including Subtotals Using DoExpressCheckoutPayment If you want the PayPal user to see subtotals of item cost shipping charges handling charges and sales tax include the following parameters in DoExpressCheckoutPayment e ITEMAMT e SHIPPINGAMT e HANDLINGAMT e TAXAMT Norte Be sure that the summed values of ITEMAMT SHIPPINGAMT HANDLINGAMT and TAXAMT equal the value of AMT You cannot include a zero amount for any of these fields and you must set all of them EXAMPLE 2 11 Including Subtotals requiredSecurityParameters METHOD DOExpressCheckoutPayment TOKEN EC 0EU150885J108392M amp PAYERID 95HR9CM6D560Q2 amp PAYMENTACTION Sale amp AMT 6 246 Request AMT 192 22 amp ITEMAMT 176 02 amp SHIPPINGAMT 14 34 amp HANDLINGAMT 1 10 amp TAXAMT 0 76 successResponseFields s TOKEN EC 0EU150885J108392M amp TRANSACT
11. Samples Using PHP on page 99 e Samples Using PHP on page 99 e Samples Using Classic ASP on page 100 Descriptions of the Samples The web samples consist of the following e Accepting PayPal in Express Checkout on page 95 e Getting Transaction Details on page 97 e Common Files on page 98 The main page of the samples index html or Default htm contains links to each sample NoTE We describe the code samples for all programming languages in this section Language specific filenames are shown as filename ext For example SetExpressCheckout ext stands for SetExpressCheckout java SetExpressCheckout php and so forth Accepting PayPal in Express Checkout This sample shows how to use Express Checkout to accept payments using PayPal Access this sample from the following choices displayed on index html or Default htm ExpressCheckout Sale Do basic checkout with PayPal In the SetExpressCheckout request the PAYMENTACTION parameter is set to Sale Name Value Pair API Developer Guide and Reference April 2007 95 NVP API Web Samples Descriptions of the Samples The primary files for this sample are TABLE C 1 Express Checkout Files File SetExpressCheckout ext ReviewOrder ext GetExpressCheckoutDetails ext Description This is the main web page for the Express Checkout sample The page allows the user to enter amount and currency type It also accept input variable paym
12. See additional error messages for details Risk Control Country Filter Failure Risk Control Max Amount Failure Long Message Correcting This Error cpp header image value exceeds maximum allowable length cpp header image value exceeds maximum allowable length ReturnURL Invalid parameter CancelURL is invalid 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 Name Value Pair API Developer Guide and Reference March 2007 73 74 Error Message Reference Express Checkout API Errors TABLE B 3 SetExpressCheckout API Errors Error Code 10539 10725 10727 10728 10729 10730 10731 10736 Short Message Payment declined by your Risk Controls settings PayPal Risk Model Shipping Address Country Error Shipping Address I 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 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 req
13. e PAYERID use the value from GetExpressCheckoutDetails response e PAYMENTACTION set to Sale This is the default value in SetExpressCheckout e AMT use the same value as in SetExpressCheckout request EXAMPLE 2 3 Making a Sale requiredSecurityParameters METHOD DOExpressCheckoutPayments TOKEN EC 0E881823PA052770A8AMT 10 008 Request PAYERID 95HR9CM6D5 602 PAYMENTACTION Sale Name Value Pair API Developer Guide and Reference April 2007 19 Accepting PayPal in Express Checkout Support giropay and electronic funds transfer successResponseFields amp TOKEN EC 0E881823PA052770A amp TRANSACT IONID 8SC56973LM923823H amp TRANSACTIONTY PE expresscheckout amp PAYMENTTY PE instant amp ORDERT IME 2006 08 22T20 16 05Z amp AMT 10 00 CURRENCY CODE USD amp FEEAMT 0 59 amp TAXAMT 0 00 amp PAYMENTSTATUS Completeds Response PENDINGREASON None amp REASONCODE None Support giropay and electronic funds transfer Initiate the Flow with SetExpressCheckout To support giropay payments you pass the following three URLs as part of the SetExpressCheckout request These URLs tell PayPal where to redirect the customer based on the success or failure of each type of payment transaction TABLE 2 1 SetExpressCheckout fields for giropay NVP SOAP Description Required GIROPAYSUCCESSURL giropaySuccessURL The URL o
14. A 9 DoExpressCheckout Payment Response Fields Field Description TOKEN The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request Character length and limitations 20 single byte characters Allowable values See the description of TOKEN in Table A 4 SetExpressCheckout Response Fields TRANSACTIONID Unique transaction ID of the payment NOTE If the PaymentAction of the request was Authorization or Order this value is your AuthorizationID for use with the Authorization amp Capture APIs Character length and limitations 19 single byte characters Possible values Transaction specific TRANSACTIONTYPE The type of transaction Character length and limitations 15 single byte characters Possible values e cart e express checkout Name Value Pair API Developer Guide and Reference April 2007 47 el NVP API Method and Field Reference Express Checkout TABLE A 9 DoExpressCheckout Payment Response Fields Continued Field Description PAYMENTTY PE Indicates whether the payment is instant or delayed Character length and limitations Seven single byte characters Possible values e none e echeck e instant ORDERT IME Time date stamp of payment Possible values Transaction specific AMT The final amount charged including any shipping and taxes from your Merchant Profile Character length and limitations Doe
15. GetExpressCheckoutDetails returns the overridden shipping address EXAMPLE 2 4 GetExpressCheckoutDetails requiredSecurityParameters METHOD GetExpressCheckoutDetails amp TOKEN EC Request 17C76533PL706494P successResponseFields sTOKEN EC 17C76533PL706494P amp PAYER abcdef anycompany com amp PAYERID 95HR9CM6D5 602 amp PAYERSTATUS verified amp FIRSTNAME John amp LASTNAME Smith amp COUNTRYCODE US amp SHIPTONAME Peter Smi ths SHIPTOSTREET 144 Main St amp SHIPTOCITY SAN JOSE amp SHI PTOSTATE CA amp SHI PTOCOUNTRYCODE US amp SHIPTOZIP 95112 Response ADDRESSID PayPal amp ADDRESSSTATUS Unconfirmed 22 April 2007 Name Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout em Changing the Language on the PayPal Login Page Using SetExpressCheckout Changing the Language on the PayPal Login Page Using SetExpressCheckout To change the language displayed on the PayPal login page set LOCALECODE to one of the allowable values in SetExpressCheckout For LOCALECODE values see Table A 2 SetExpressCheckout Request Parameters The following example sets LOCALECODE to French EXAMPLE 2 5 Changing the PayPal Login Page Language to French requiredSecurityParameters METHOD SetExpressCheckoutsAMT 10 008 CURRENCYCODE EUR amp RETURNURL https www anycompany com orderprocessing orderrevi
16. If your application is behind a proxy server you must enable proxy support in the Web config file For details on how to use the system net element in the Web config file please refer to Configuring Internet Applications in the MSDN Library Uninstalling the SDK To uninstall the SDK use the Microsoft Windows control panel Add Remove Programs Complete SDK and API Class Documentation Complete Microsoft NET Ndoc documentation for all PayPal SDK interfaces classes methods structures and data types are included with the SDK distribution To view the documentation open the following file with your web browser SDK root docs PayPalBaseAPI chm Profiles Before the SDK can be used it must know the profile of the user accessing its services A profile is a collection of information about a merchant or developer who uses the PayPal SDK An API profile is associated with API Services and includes e A PayPal API username and password e Ifyou are using API certificates the path to the API certificate in P12 format and the private key password to that certificate e Ifyou are using API signatures the signature string e The optional name of a third party who authorizes the caller to invoke PayPal APIs on his behalf This third party is called a subject e The PayPal environment for processing API calls live or sandbox An EWP profile is associated with EWP Services includes e The path to the merchant s local copy of
17. Payer Details Using GetExpressCheckoutDetails 19 4 Making a Sale Using DoExpressCheckoutPayment 19 Support giropay and electronic funds transfer 2 var arr rakk kr rn 20 Initiate the Flow with SetExpressCheckout 2 aar arr re 20 Redirecting the Customer to PayPal 2 0 0 00002 krakk ee 20 Name Value Pair API Developer Guide and Reference April 2007 ee Contents Completing the Transaction 0 vr ra 21 Controlling the Shipping Address Using SetExpressCheckout 21 Suppressing Display of Shipping Address on PayPal 21 Overriding the Shipping Address Stored on PayPal 22 Changing the Language on the PayPal Login Page Using SetExpressCheckout 23 Changing the Logo on the PayPal Pages Using SetExpressCheckout 23 Specifying a Custom Payment Page Style 22 av vr vrak kran 23 Specifying Logo and Color Settings Individually 24 Form Filling Your Payment Review Page Using GetExpressCheckoutDetails 24 Making a Sale Using DoExpressCheckoutPayment LL aa vr rar ran 25 Changing the URL for IPN Using DoExpressCheckoutPayment 25 Including Line Item Details Using DoExpressCheckoutPayment 26 Including Subtotals Using DoExpressCheckoutPayment 27 Updating Order Details Using DoExpressCheckoutPayment 27 Upd
18. REPUBLIC Code HM VA HN HK HU IS IN ID IR IQ IE IM TE IT JM JP JE JO KE a KW KG LA Country LATVIA LEBANON LESOTHO LIBERIA LIBYAN ARAB JAMAHIRIYA LIECHTENSTEIN LITHUANIA LUXEMBOURG MACAO MACEDONIA THE FORMER YUGOSLAV REPUBLIC OF MADAGASCAR MALAWI MALAYSIA MALDIVES MALI MALTA MARSHALL ISLANDS MARTINIQUE MAURITANIA MAURITIUS MAYOTTE MEXICO MICRONESIA FEDERATED STATES OF MOLDOVA REPUBLIC OF MONACO MONGOLIA MONTSERRAT Code LV LB LS LR LY LI LT LU MO MK MG MW MY MV ML MT MH MQ MR MU YT MX FM MD MC MN MS Country Codes 120 Country MOROCCO MOZAMBIQUE MYANMAR NAMIBIA NAURU NEPAL NETHERLANDS NETHERLANDS ANTILLES NEW CALEDONIA NEW ZEALAND NICARAGUA NIGER NIGERIA NIUE NORFOLK ISLAND NORTHERN MARIANA ISLANDS NORWAY OMAN PAKISTAN PALAU PALESTINIAN TERRITORY OCCUPIED PANAMA PAPUA NEW GUINEA PARAGUAY PERU Code NO OM PK PW PS PA PG PY PE Country PHILIPPINES PITCAIRN POLAND PORTUGAL PUERTO RICO QATAR REUNION ROMANIA RUSSIAN FEDERATION RWANDA SAINT HELENA SAINT KITTS AND NEVIS SAINT LUCIA SAINT PIERRE AND MIQUELON SAINT VINCENT AND THE GRENADINES SAMOA SAN MARINO SAO TOME AND PRINCIPE SAUDI ARABIA SENEGAL SERBIA AND MONTENEGRO SEYCHELLES SIERRA LEONE SINGAPORE SLOVAKIA SLOVENIA Code PH PN PL PT PR QA RE RO RU RW SH KN
19. SDK Log Levels To enable logging for your SDK based web applications add the following lines inside the lt configuration gt block of the Web config file You can copy these lines from the SDK roof samplesNASPNETAWeb config file e You might want to change the value of the file element to write log records to a location you prefer e Set the value of the level element to the desired detail described in Table E 4 SDK Logging Levels lt configSections gt lt section name log4net type log4net Config Log4NetConfigurationSectionHandler log4net gt lt configSections gt lt log4net gt lt appender name PAYPALLOGFILE type log4net Appender RollingFileAppender gt lt file value logs paypal sdk log gt lt appendToFile value true gt lt encoding value UTF 8 gt lt rollingStyle value 5 gt lt maxSizeRollBackups value 10 gt lt maximumFileSize value 10MB gt lt staticLogFileName value true gt lt layout type log4net Layout PatternLayout gt lt conversionPattern value d dd MMM yyyy HH mm ss 5p C 1 m amp n gt lt layout gt lt appender gt 112 April 2007 Name Value Pair API Developer Guide and Reference The ASP NET SDK ad Complete SDK and API Class Documentation lt logger name com paypal sdk gt lt level value ALL gt lt appender ref ref PAYPALLOGFILE gt lt logger gt lt log4net gt Enabling Proxy Support
20. Samples First make sure that you have installed the required software and the samples You can run the samples by entering the following address in a web browser http name_of_Serverport PayPalClassicAspNvpSamples Default htm 100 April 2007 Name Value Pair API Developer Guide and Reference NVP API Web Samples aa Samples Using ColdFusion Samples Using ColdFusion This section contains information for configuring and running the NVP API Web Samples Using ColdFusion Required Software The following software is required TABLE C 5 Supported Standards Standard Version Download Location ColdFusion 7 x MX http www adobe com products coldfusion Download and Unzip the Samples The latest version of the Web Samples are available at https www paypal com IntegrationCenter ic nvp html 1 Download the zipfile distribution 2 Unzip the zipfile to any directory of you choose Installing the Samples Note The samples assume that ColdFusion is running on Microsoft Windows 3 Copy the sample folder to your ColdFusion application server web document root ColdFusionMX7_root_directory wwwroot Running the Samples First make sure that you have installed the required software and the samples You can run the samples by entering the following address in a web browser http name_of_Serverport cf nvp samples index html Name Value Pair API Developer Guide and Reference April 2007 101 me NVP API Web S
21. Search by transaction status No e Pending The payment is pending The specific reason the payment is pending is returned by the GetTransactionDetails API PendingReason field e Processing The payment is being processed e Success The payment has been completed and the funds have been added successfully to your account balance e Denied You denied the payment This happens only if the payment was previously pending e 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 TABLE A 13 TransactionSearch Response Fields Field Description L TIMESTAMPn The date and time in UTC GMT format the transaction occurred These parameters should be ordered sequentially beginning with 0 for example L TIMESTAMPO L TIMESTAMPI and so forth L TIMBZONEnN The time zone of the transaction These parameters should be ordered sequentially beginning with 0 for example L TIMEZONEO L TIMEZONEL and so forth L TYPEN The type of the transaction These parameters should be ordered sequentially beginning with 0 for example L TYPEO L TYPEL and so forth L EMAILIN The email address of either the payer or the payment recipient the payee If the payment amount is positive this field is the recipient of the funds If the payment is negative this field is the paying cust
22. 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 The masspay receiver type is not a recognizable type The user account is locked The number of input records is greater than maximum allowed 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 90 March 2007 Name Value Pair API Developer Guide and Reference Error Message Reference MassPay API Errors TABLE B 8 MassPay API Errors Error Code 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 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 The currency is missing Currency is not supported The amount is not a valid number The amount exceeds the max limit of a single mass
23. TABLE A 7 NVP API Method and Field Reference Express Checkout DoExpressCheckoutPayment Parameters Continued Parameter L NUMBERN L OTYn L TAXAMTn L AMTn Shipping Address Description Item number Character length and limitations 127 single byte characters These parameters should be ordered sequentially beginning with 0 for example L NUMBERO L NUMBER and so forth Item quantity Character length and limitations Any positive integer These parameters should be ordered sequentially beginning with 0 for example L QTYO L QTY and so forth Item sales tax 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 optional thousands separator must be a comma Equivalent to nine characters maximum for USD These parameters should be ordered sequentially beginning with 0 for example L TAXAMTO L_TAXAMT1 and so forth Cost of item 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 optional thousands separator must be a comma Equivalent to nine characters maximum for USD These parameters should be ordered sequentially beginning with 0 for example L AMTO L AMT1 and so forth Optional shipping address The parameters for the optional Ship to Ad
24. additional error messages for details The transaction id is not valid 68 March 2007 Name Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B 3 SetExpressCheckout API Errors Error Code 10007 10102 10103 10402 10404 10405 10407 10409 Short Message Permission denied PaymentActio n of Order Temporarily Unavailable Please use another Solution Type Authorization only is not allowed for merchant 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 You re not authorized to access this info Long Message Correcting This Error You do not have permissions to make this API call PaymentAction of Order is temporarily unavailable Please try later or use other PaymentAction Your Solution Type is temporarily unavailable If possible please use another Solution Type This merchant account is not permitted to set PaymentAction to Authorization Please contact Customer Service ReturnURL is missing CancelURL is missing Invalid buyer email address BuyerEmail Express Checkout token was issued for a merchant account other than yours Name Value Pair AP
25. and Reference April 2007 13 14 Overview Technical Details Request Format Each NVP request consists of required and optional parameters and their values Parameter names are not case sensitive The examples in this document use UPPERCASE for parameter names and divide the parameters into required security parameters and body parameters TABLE 1 3 General Format of a Request Required USI Security amp SUBJ Parameters The fo USER PWD ER apiUsername amp PWD apiPassword amp SIGNATUR ECT optionalThirdPartyEmailAddressV llowing parameters are always required VERSION 2 3 E apiSignature ERSION 2 3 NOTE The examples show the required security parameters like this Body EMI Parameters requiredSecurityParameters ETHOD methodName otherRequiredAndOptionalParameters In practice you need to concatenate all parameters and values into a single URL encoded string After the METHOD parameter you can specify the parameters in any order Required Security Parameters The required security parameters are described below These are your PayPal API credentials TABLE 1 4 Required Security Parameters API Credentials Parameter Value USER Required Your PayPal API Username PWD Required Your PayPal API Password VERSION 2 3 Required SIGNATURE Optional Your PayPal API signature string If you use an API certificate do not include this parameter SUBJECT Optional make this c
26. cost of item You can detail as many items as you want Beginning with 0 append an index number to the field name and increment that index number by one for each item The following example sets line item details for two items These details are recorded on PayPal EXAMPLE 2 10 Including Line Item Details Request requiredSecurityParameters METHOD DOExpressCheckoutPayments TOKEN EC 4XH62109C8044521N8PAYERID 95HR9CM6D5 602 amp PAYMENTACTION SalesAMT 6 248 ITEMAMT 5 75 amp TAXAMT 0 49 amp L NUMBERO 1 amp L NAME0 A Tale of Two Cities amp L AMT0 2 508 L QTYO 1 amp L TAXAMTO 0 21 amp L NAME1 Oliver Twist amp L NUMBER1 2 amp L AMT1 3 258L QTY1 1 amp L TAXAMT1 0 28 Response successResponseFields sTOKEN EC 4XH62109C8044521N amp TRANSACTIONID 77U91743M2649930P amp TRANSACTIONTYPE expresscheckout amp PAYMENTTYPE instant ORDERT IME 2006 08 22T22 49 50Z amp AMT 6 24 amp CURRENCY CODE USD amp FEEAMT 0 48 amp TAXAMT 0 28 amp PAYMENTSTATUS Completed amp PENDINGREASON None amp REASONCODE None If you specify L_AMTn you must specify the ITEMAMT parameter The values for L_AMTn and L OTYn should add up to the ITEMAMT If you specify L TAXAMTn you must specify the TAXAMT parameter The values for L 26 TAXAMTn and L QTYn should add up to TAXAMT April 2007 Name Value Pair API Developer Guide and Reference
27. is not valid of an invalid argument See additional error messages for details 10007 Permission denied You do not have permissions to search for this transaction 10007 Permission denied You do not have permissions to make this API call 11002 Search warning The number of results were truncated Please change your search parameters if you wish to see all your results GetTransactionDetails API Errors TABLE B 7 GetTransactionDetails API Errors Short Error Code Message Long Message 10001 Internal Error Internal Error MassPay API Errors TABLE B 8 MassPay API Errors Short Error Code Message Long Message 10001 Invalidaccount The transaction failed as a result of an invalid credit card number number Check the number or attempt with another card 10001 Internal Error Internal Error 10001 Internal Error The transaction could not be loaded 10001 ButtonSource The transaction could not be loaded value truncated Name Value Pair API Developer Guide and Reference March 2007 89 Error Message Reference MassPay API Errors TABLE B 8 MassPay API Errors Error Code 10001 10002 10004 10004 10004 10004 Short Message Transaction refused because of an invalid argument See additional error messages for details Account locked Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument
28. parameter missing Version Required parameter missing Amt Invalid parameter MaxAmt Invalid parameter NotifyURL Invalid parameter ShipToStreet Invalid parameter ShipToStreet2 Invalid parameter ShipToCity Invalid parameter ShipToState Invalid parameter ShipToZip Invalid parameter Country Invalid parameter ReqConfirmShipping Invalid parameter Noshipping Invalid parameter AddrOverride Invalid parameter LocaleCode Invalid parameter PaymentAction Invalid parameter Name Value Pair API Developer Guide and Reference March 2007 65 Error Message Reference Validation Errors TABLE B 1 Validation Errors Error Code Short Message Long Message 81219 Invalid Parameter ItemAmt Invalid parameter 81220 Invalid Parameter ShippingAmt Invalid parameter 81221 Invalid Parameter HandlingTotal Amt Invalid parameter 81222 Invalid Parameter TaxAmt Invalid parameter 81223 Invalid Parameter IPAddress Invalid parameter 81224 Invalid Parameter ShipToName Invalid parameter 81225 Invalid Parameter L Amt Invalid parameter 81226 Invalid Parameter Amt Invalid parameter 81227 Invalid Parameter L TaxAmt Invalid parameter 81229 Invalid Parameter CompleteType Invalid parameter 81230 Invalid Parameter CurrencyCode Invalid parameter 81232 Invalid Parameter TransactionEntity Invalid parameter 81234 Invalid Parameter ExpDate Invalid parameter 81235 Invalid Parameter FirstName Invalid parameter 812
29. separator must be a comma Description of items the customer is purchasing Character length and limitations 127 single byte alphanumeric characters A free form field for your own use Character length and limitations 256 single byte alphanumeric characters Your own invoice or tracking number Character length and limitations 127 single byte alphanumeric characters An identification code for use by third party applications to identify transactions Character length and limitations 32 single byte alphanumeric characters Required Yes Yes Yes Yes Yes No 44 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout TABLE A 7 DoExpressCheckoutPayment Parameters Continued Parameter Description Required NOTIFYURL Your URL for receiving Instant Payment Notification IPN about this No transaction NOTE If you do not specify this value 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 ITEMAMT Sum of cost of all items in this order No Limitations Must not exceed 10 000 USD in any currency No currency symbol Must have two decimal places decimal separator must be a period and the optional thousands separator must be a comma NOTE ITEMAMT is required if you specify a value for L_AMTn SHIPPINGAMT Tota
30. that public certificate e The private key password for that public certificate e The path to a merchant s private key file for digitally signing data Name Value Pair API Developer Guide and Reference April 2007 113 el The ASP NET SDK Profiles e The URL to which the button form POSTs e The optional URL of a payment button image The default is PayPal s standard Buy Now button For more information about how EWP works see the Website Payments Standard Integration Guide available at https www paypal com en US pdf PP WebsitePaymentsStandard IntegrationGuide pdf Overview to Profile related Classes The primary interfaces and classes for SDK profiles are described in Table E 5 Summary of ASP NET SDK Profile related Interfaces and Classes TABLE E 5 Summary of ASP NET SDK Profile related Interfaces and Classes Interface Class Description TAPIProfi le interface This interface defines the basic information that PayPal needs to know about a user of the PayPal Web Service APIs Developers must create an instance of LAPIProfile for each account that accesses the APIs For single merchant developers only a single IAPIProfile instance is needed PayPal provides a default implementation class called DefaultAPIProfile suitable for the needs of most SDK developers However you are free to write a custom implementation if you need additional functionality the default class does not offer ProfileFactory class This class cre
31. to any information herein without further notice Contents 3 E This Document 222 aa arva kaka 7 Intended Audience 22 a aar ee ee 7 Documentation Problems nn 7 Revision History a 4 s 44 bee EGG EG Bd hh eee GE ee 8 Chapter 1 OvervieWw m s bk GK Introducing the PayPal NVP APL LL Lav vr vr vr a 9 Integrating with the PayPal API LL aa rav 2 o akk nrk 9 Basic Steps 2 arr rv ee 10 Create a Web Application 0 00002 ee ee 10 Get API Credentials 2 20002 kran 10 Create and Post the Request 000000 eee ee eee 11 Interpret the Response 0 00 00 eee ee 11 Taking Your Application Live 2 2222 rv krakk 11 Set Up a PayPal Business Account Lava vr rakk 11 Set Up API Credentials 2 arva rn anna 11 Modify Your Code a s es x eei R R R RR RR RR R R RR R 12 Technical Details a 12 Request Response Model arr 12 Request Format doc coca wt adv are S R a he ere ren EET a en Ge a K 14 Response Format 2 2 000 ee 15 Posting Using HTTPS vs s er avd en ST ha SEG ERE EE EEE GE 16 Chapter 2 Accepting PayPal in Express Checkout 17 Basic Checkout with PayPal 2 2 0 vr krana kara 17 1 Starting the Checkout Using SetExpressCheckout 18 2 Redirecting the Customer s Browser to PayPal Login Page 18 3 Getting
32. 106 AUCTIONITEMNUMBER 52 AUD 35 Australian Dollar 35 AuthorizationID 47 B BANKTXNPENDINGURL 37 BUILD 15 16 63 BUSINESS 42 BUTTONSOURCE 44 BUYERID 60 Name Value Pair API Developer Guide and Reference C CAD 35 Canadian Dollar 35 Canceled Reversal 57 CANCELURL 36 certificate sample 108 116 Certificate APIProfile class 106 CHF 35 chm documentation 113 CLASSPATH 104 CLOSINGDATE 60 ColdFusion 101 Completed 57 CORRELATIONID 15 16 63 COUNTRYCODE 42 currency codes 35 CURRENCYCODE 37 45 48 60 CUSTOM 38 43 44 58 Czech Koruna 35 CZK 35 D Danish Krone 35 Default APIProfile class 114 Denied 57 Denied transaction status 53 DESC 37 44 digital certificate sample 108 116 DKK 35 documentation 111 E EFFECTIVEDATE 59 EMAIL 37 42 55 TransactionSearch 51 EMAILSUBJECT 61 ENDDATE 51 March 2007 123 Index EUR 35 J Euro 35 l G EWP profile apanese Yen Java Development Kit 1 4 103 defined 106 113 j aes Javadoc documentation for PayPal SDK 105 EWPProfile interface 107 114 EXCHANGERATE 48 57 Je Expired 57 Express Checkout 107 115 K F Koruna 35 FEEAMT 48 57 Krona 36 FEEREFUNDAMT 50 Krone 35 FIRSTNAME 42 51 55 Forint 36 L L 46 G L AMTn 26 46 54 59 60 L DESCn 59 GBP 35 Get Transaction Details 115 GetTransactionDetails 33 107 GIROPAYCANCELURL 37 GIROPAYSUCCESSURL 36 GROSSREFUNDAMT 50 L EMAILn 53 60 L FEEAMTn 54 L NAMEn 26 45 53 L NETAMTn 54 L NOTEn 61 L N
33. 36 Invalid Parameter LastName Invalid parameter 81237 Invalid Parameter Street Invalid parameter 81238 Invalid Parameter Street2 Invalid parameter 81239 Invalid Parameter City Invalid parameter 81243 Invalid Parameter RefundType Invalid parameter 81244 Invalid Parameter StartDate Invalid parameter 81245 Invalid Parameter EndDate Invalid parameter 81247 Invalid Parameter CreditCardType Invalid parameter 81248 Invalid Parameter Username Invalid parameter 81249 Invalid Parameter Password Invalid parameter 81250 Invalid Parameter Version Invalid parameter 81251 Internal Error Internal Service Error 66 March 2007 Name Value Pair API Developer Guide and Reference Error Message Reference General API Errors oe General API Errors TABLE B 2 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 Authorizatio
34. 67386 gt Request amp REFUNDTYPE Full successResponseFields sREFUNDTRANSACTIONID 4RP55200GJ177180N Response amp FEEREFUNDAMT 4 01 amp GROSSREFUNDAMT 127 87 NETREFUNDAMT 123 86 Partial Refunds To refund a partial amount set REFUNDTYPE to Partial and set the AMT EXAMPLE 3 2 Refunding A Partial Amount requiredSecurityParameters sMETHOD RefundTransaction Request amp TRANSACT IONI D 9CX07910UV614511L amp REFUNDTYPE Partial amp AMT 12 95 successResponseFields REFUNDTRANSACTIONID 1H0011898K637700R Response amp FEEREFUNDAMT 0 38 amp GROSSREFUNDAMT 12 95 amp NETREFUNDAMT 12 57 Name Value Pair API Developer Guide and Reference April 2007 31 Back Office Administration ES Searching for Transactions Using TransactionSearch Including a Note with the Refund Whether the refund is full or partial you can also include a note about the refund EXAMPLE 3 3 Including a Note with the Refund frequiredSecurityParametersJsMETHOD RefundTransaction amp TRANSACTIONID 01945456967386 7 Request amp REFUNDTYPE Partial amp AMT 12 95 amp NOTE Customer changed mind successResponseFields sREFUNDTRANSACTIONID 1H0011898K637700R Response amp FE EREFUNDAMT 0 38 amp GROSSREFUNDAMT 12 95 amp NETREFUNDAMT 12 57 Searching for Transactions Using TransactionSearch To find all transactions that occurred on a particular date use Transaction
35. 8 Short Message Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Long Message Correcting This Error Value of OrderDescription element has been truncated Value of Custom element has been truncated PageStyle value exceeds maximum allowable length cpp header image value exceeds maximum allowable length cpp header image value exceeds maximum allowable length 72 March 2007 Name Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B 3 SetExpressCheckout API Errors Error Code 10439 10440 10471 10472 10537 10538 Short Message Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument
36. 83E5565113B successResponseFields sTOKEN EC 3DJ7 8083ES565113B amp EMAIL abcdef anyemail com amp PAYERID 95HR9CM6D5 602 amp PAYERSTATUS veri fied amp FIRSTNAME John amp LASTNAME Smi th amp COUNTRYCODE US amp SHIPTONAME John Smith amp SHIPTOSTREET 144 Main St SHIPTOCITY SantJose amp SHI PTOSTATE CA amp SHI PTOCOUNTRY CODE US amp SHIPTOZIP 99221 amp Response ADDRESSID PayPal amp ADDRESSSTATUS Confirmed 24 April 2007 Name Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout Making a Sale Using DoExpressCheckoutPayment 2 Get the payer name from the following parameters in GetExpressCheckoutDetails response e SALUTATION e FIRSTNAME e MIDDLENAME e LASTNAME e SUFFIX Get the shipping address from the following parameters in GetExpressCheckoutDetails response e SHIPTONAME e SHIPTOSTREET e SHIPTOSTREET2 e SHIPTOCITY e SHIPTOSTATE e SHIPTOCOUNTRYCODE e SHIPTOPHONENUM e SHIPTOZIP Making a Sale Using DoExpressCheckoutPayment Use DoExpressCheckoutPayment to make a final sale For more information see Basic Checkout with PayPal on page 17 Changing the URL for IPN Using DoExpressCheckoutPayment You can change the URL for receiving Instant Payment Notification IPN about this transaction
37. AMT 27 45 SHIPTOCITY 40 43 46 55 SHIPTOCOUNTRYCODE 40 43 47 55 SHIPTONAME 40 42 46 55 SHIPTOPHONENUM 47 55 SHIPTOSTATE 40 43 47 56 SHIPTOSTREET 40 42 46 56 SHIPTOSTREET2 40 43 47 56 SHIPTOZIP 40 43 47 55 SIGNATURE 14 SignatureAPIProfile class 106 Singapore Dollar 36 source files 111 sre 111 STARTDATE 32 51 STATUS 53 SUBJECT 14 SUBSCRIPTIONDATE 59 126 March 2007 SUBSCRIPTIONID 59 Success transaction status 53 successResponseFields defined 15 SUFFIX 42 52 55 Swedish Krona 36 Swiss Franc 35 system store 116 Y TAXAMT 27 45 48 57 TOKEN 47 DoExpressCheckoutPayment 44 GetExpressCheckoutDetails 41 GetExpressCheckoutDetails response 42 SetExpressCheckout 38 SetExpressCheckout response 41 Token 18 41 token 18 41 TRANSACTIONCLASS 52 TRANSACTIONID DoExpressCheckoutPayment response 47 GetTransactionDetails 54 GetTransactionDetails response 56 RefundTransaction 50 TransactionSearch 51 TransactionSearch 32 107 115 TRANSACTIONTYPE 47 56 TransactionType 49 58 U U S Dollar 36 URL format 12 UrlDecode 13 urldecode 13 URLDecoder 13 URLDecodeurlEncodedString 13 URLEncode 13 UrlEncode 13 urlencode 13 URL encoded string 14 URLEncodedFormatstring 13 URLEncoder encode 13 URL encoding 13 15 16 35 ASP NET 13 Classic ASP 13 Name Value Pair API Developer Guide and Reference ColdFusion 13 Java 13 PHP 13 USD 36 USER 14 USERNAME 59 UTC GMT 53 V VERSION 15 16
38. API Errors oe TABLE B 6 RefundTransaction API Errors Short Error Code Message Long Message Correcting This Error 10009 Transaction Account is restricted refused 10009 Transaction You can not refund this type of transaction refused 10009 Transaction You can not do a partial refund on this refused transaction 10009 Transaction The account for the counterparty is locked or refused 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 B 2 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 Name Value Pair API Developer Guide and Reference March 2007 87 Error Message Reference TransactionSearch API Errors TABLE B 2 TransactionSearch API Errors Error Code Short Message Long Message 10004 Transaction refused because Start date is invalid of an invalid argument See additional error messages for details 10004 Transaction refused because End
39. BP Pound Sterling Name Value Pair API Developer Guide and Reference April 2007 35 el NVP API Method and Field Reference Express Checkout TABLE A 1 PayPal Supported Currencies and Currency Codes for Transactions ISO 4217 Code Currency HKD Hong Kong Dollar HUF Hungarian Forint JPY Japanese Yen NOK Norwegian Krone NZD New Zealand Dollar PLN Polish Zloty SEK Swedish Krona SGD Singapore Dollar USD U S Dollar Express Checkout SetExpressCheckout Request TABLE A 2 SetExpressCheckout Request Parameters Parameter Description Required METHOD Name of the API SetExpressCheckout Yes RETURNURL URL to which the customer s browser is returned after choosing to Yes pay with PayPal NOTE PayPal recommends that the value be the final review page on which the customer confirms the order and payment Character length and limitations no limit CANCELURL URL to which the customer is returned if he does not approve the Yes use of PayPal to pay you NOTE PayPal recommends that the value be the original page on which the customer chose to pay with PayPal Character length and limitations no limit GIROPAYSUCCESSURL URL of your website where the user gets redirected once he No successfully completed a transaction with giropay This page should recommended be the order confirmation page 36 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference Expre
40. CODE None amp SALESTAX 0 00 amp L OTYO 1 Name Value Pair API Developer Guide and Reference April 2007 33 T Back Office Administration Viewing Details of a Single Transaction Using GetTransactionDetails 34 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference General Characteristics of Requests and Parameters Parameters The request parameter string follows the query component syntax defined in Uniform Resource Identifier URI Generic Syntax Parameter names and their values can be upper or lowercase We show parameter names in uppercase for clarity All values must be URL encoded Multi Value Fields Fields that accept multiple values have names like this L FIELDNAMEn where L is literal FIELDNAME is the name of the parameter and n is an index number starting at 0 and incremented by one for each value of the field Index numbers must be sequential For example if an order contains multiple items you can add an item cost for each item using the L AMTn parameter L AMTO 4 958L AMT1 6 72 amp L AMT2 7 95 PayPal Supported Transactional Currencies The following currencies are supported by PayPal for use in transactions TABLE A 1 PayPal Supported Currencies and Currency Codes for Transactions ISO 4217 Code Currency AUD Australian Dollar CAD Canadian Dollar CHF Swiss Franc CZK Czech Koruna DKK Danish Krone EUR Euro G
41. D nin the individual item L_AMTn Payment amount Yes CURRENCYCODE A three character currency code for one of the currencies listed in PayPay Yes Supported Transactional Currencies Default USD L EMAILN Email address of recipient Depends NOTE You must specify either L EMAILn or L_RECEIVERIDn but you e must not mix them Use only one or the other but not both in a single aay a request a Character length and limitations 127 single byte characters maximum These parameters should be ordered sequentially beginning with 0 for example L EMAILO L EMAILI and so forth L RECEIVERIDN Unique PayPal customer account number This value corresponds to the Depends value of PAYERID returned by GetTransactionDetails on These parameters should be ordered sequentially beginning ae j with 0 for example L RECEIVERIDO L_RECEIVERID1 and so forth 60 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference Mass Payment TABLE A 16 MassPay Parameters Continued Require Parameter Description d L UNIQUEIDN Transaction specific identification number for tracking in an accounting No system Character length and limitations 30 single byte characters No whitespace allowed These parameters should be ordered sequentially beginning with 0 for example L UNIQUEIDO L UNIQUEIDL and so forth L NOTEN Custom note for each recipient No Character
42. EROON CANADA CAPE VERDE CAYMAN ISLANDS CENTRAL AFRICAN REPUBLIC CHAD Code BY BE BZ BJ BM BT BO BA BW BV BR IO BN BG BF BI CM CA CV KY CF TD 117 Country Codes 118 Country CHILE CHINA CHRISTMAS ISLAND COCOS KEELING ISLANDS COLOMBIA COMOROS CONGO CONGO THE DEMOCRATIC REPUBLIC OF THE COOK ISLANDS COSTA RICA COTE D TVOIRE CROATIA CUBA CYPRUS CZECH REPUBLIC DENMARK DJIBOUTI DOMINICA DOMINICAN REPUBLIC ECUADOR EGYPT EL SALVADOR EQUATORIAL GUINEA ERITREA ESTONIA ETHIOPIA Code CL CN CX CC CO CG CD CK CR CI HR CU CY CZ DK DJ DM DO EC EG SV GQ ER EE ET Country FALKLAND ISLANDS MALVINAS FAROE ISLANDS FIJI FINLAND FRANCE FRENCH GUIANA FRENCH POLYNESIA FRENCH SOUTHERN TERRITORIES GABON GAMBIA GEORGIA GERMANY GHANA GIBRALTAR GREECE GREENLAND GRENADA GUADELOUPE GUAM GUATEMALA GUERNSEY GUINEA GUINEA BISSAU GUYANA HAITI Code FK FO FJ FI FR GF PF TF GA GM GE DE GH GI GR GL GD GP GU GT GG GN GW GY HT Country HEARD ISLAND AND MCDONALD ISLANDS HOLY SEE VATICAN CITY STATE HONDURAS HONG KONG HUNGARY ICELAND INDIA INDONESIA IRAN ISLAMIC REPUBLIC OF IRAQ IRELAND ISLE OF MAN ISRAEL ITALY JAMAICA JAPAN JERSEY JORDAN KAZAKHSTAN KENYA KIRIBATI KOREA DEMOCRATIC PEOPLE S REPUBLIC OF KOREA REPUBLIC OF KUWAIT KYRGYZSTAN LAO PEOPLE S DEMOCRATIC
43. Error or Warning API response fields are not returned An error response has the following general format TABLE 1 6 Format of an Error Response Response ACK Error amp TIMESTAMP date t imeOfResponse amp Multiple errors can be returned Fields on Error CORRELATIONID debuggingToken amp VERSION 2 300000 Each set of errors has a different BUILD bui ldNumber amp l ERRORCODEO errorCode amp numeric suffix starting with 0 L SHORTMESSAGEO shortMessage and incremented by one for each LONGMESSAGEO longMessage EL OL amp L SEVERITYCODEO severityCode For possible causes of errors and how to correct them see the explanation of the specific error code short message and long message in Appendix B Error Message Reference ACK Parameter Values The following table lists values for the ACK parameter TABLE 1 7 ACK Parameter Values Type of Response Value Successful response Success SuccessWithWarning Error response Error Warning Posting Using HTTPS Your web application posts the URL encoded NVP string over an HTTPS connection to one of the PayPal API servers PayPal provides a live server and a Sandbox server that allows you to process transactions in a test environment API Servers for API Signature Security If you use an API signature post the request to one of these servers Sandbox https api 3t sandbox paypal com nvp Live https api 3t paypa
44. GetTransactionDetails Request Parameters Parameter Description Required METHOD Name of the API GetTransactionDetails Yes TRANSACTIONID Unique identifier of a transaction Yes NOTE The details for some kinds of transactions cannot be retrieved with GetTransactionDetails You cannot obtain details of bank transfer withdrawals for example Character length and limitations 17 single byte alphanumeric characters TABLE A 15 GetTransactionDetails Response Fields Parameter Description RECEIVERBUSINESS 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 RECEIVEREMAIL Primary email address of the payment recipient the 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 RECEIVERID Unique account ID of the payment recipient the seller This value is the same as the value of the recipient s referral ID 54 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference GetTransactionDetails ae TABLE A 15 GetTransactionDetails Response Fields Continued Parameter Description EMAIL Email add
45. I Developer Guide and Reference March 2007 69 Error Message Reference Express Checkout API Errors TABLE B 3 SetExpressCheckout API Errors Short Error Code Message Long Message Correcting This Error 10410 Invalid token Invalid token 10411 This Express This Express Checkout session has expired The token returned by Checkout Token value is no longer valid SetExpressCheckout session has response expires after expired three hours If you attempt to send the DoExpressCheckoutPaym ent after that time you will receive error code 10411 in the DoExpressCheckoutPaym ent response 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 SetExpressCheckout request However because you already know the final OrderTotal be sure to update the value for that element if appropriate You might also want to update the values for ReturnURL and CancelURL if necessary 70 March 2007 Name Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors Ia TABLE B 3 SetExpressCheckout API Errors Short Error Code Message Long Message Correcting This Error 10412 Duplica
46. I Developer Guide and Reference April 2007 49 S NVP API Method and Field Reference RefundTransaction RefundTransaction TABLE A 10 RefundTransaction Request Parameters Parameter Description Required METHOD Name of API call RefundTransaction Yes TRANSACTIONID Unique identifier of a transaction Yes Character length and limitations 17 single byte alphanumeric characters REFUNDTYPE Type of refund you are making Yes e Other e Full e Partial AMT Refund amount No Amount is required if RefundType is Partial NOTE If RefundType is Full do not set Amount unless your merchant account has been enabled to issue refunds greater than the amount in referenced transactions NOTE Custom memo about the refund No Character length and limitations 255 single byte alphanumeric characters TABLE A 11 DoRefund Response Fields Field Description REFUNDTRANSACTIONID Unique transaction ID of the refund Character length and limitations 17 single byte characters NETREFUNDAMT Amount subtracted from PayPal balance of original recipient of payment to make this refund FEEREFUNDAMT Transaction fee refunded to original recipient of payment GROSSREFUNDAMT Amount of money refunded to original payer TransactionSearch With TransactionSearch you must always set the StartDate field Some other behavior e Setting TransactionID overrides all other fields even the required StartDate field e The
47. IONID 2 9W817045L6797418 amp TRANSACTIONTY PE expresscheck out amp PAYMENTTYPE instant KORDE RT IME 2006 08 23T16 20 22Z8AMT 192 22 amp CURRENCYCODE USD amp FEEAMT 5 87 amp TAXAMT 0 76 amp PAYMENTSTATUS Response Completed amp PENDINGREASON None amp REASONCODE None Updating Order Details Using DoExpressCheckoutPayment You may need to update order details on PayPal if the customer makes a change to the order after returning to your order review page If the change causes new values for one or more of the following parameters you need to update the order details on PayPal using DoExpressCheckoutPayment Name Value Pair API Developer Guide and Reference April 2007 27 Fe Accepting PayPal in Express Checkout Updating the Shipping Address Using DoExpressCheckoutPayment ESC item description e e CUSTOM field for your own use e INVNUM your invoice or tracking number These three parameters may have been set in SetExpressCheckout EXAMPLE 2 12 Updating Order Details requiredSecurityParameters METHOD DoExpressCheckoutPayments TOKEN EC 5JA9268562132991T amp PAYERID 95HR9CM6D5 602 amp PAYMENTACT ION Sale amp AMT 10 00 amp Request DESC Order for 5 books amp CUSTOM Thank you for your business amp INVNUM ABC1234567 successResponseFields s TOKEN EC 5JA9268562132991T amp TRANSAC
48. LC PM VC WS SM ST SA SN CS SC SL SG SK SI Country 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 TANZANIA UNITED REPUBLIC OF THAILAND TIMOR LESTE TOGO TOKELAU TONGA TRINIDAD AND TOBAGO TUNISIA TURKEY TURKMENISTAN TURKS AND CAICOS ISLANDS TUVALU Code SB SO ZA GS ES LK SD SR SJ SZ SE CH SY TW TJ TZ TH TL TG TK TO TT TN TR TM TC TV UKRAINE UNITED ARAB EMIRATES UNITED KINGDOM UNITED STATES UNITED STATES MINOR OUTLYING ISLANDS URUGUAY UZBEKISTAN VANUATU VENEZUELA VIET NAM VIRGIN ISLANDS BRITISH VIRGIN ISLANDS U S WALLIS AND FUTUNA WESTERN SAHARA YEMEN ZAMBIA ZIMBABWE Code Country Codes 122 Index A ACCT 51 ACK 15 16 63 Add Remove Programs 113 ADDRESSOWNER 55 ADDRESSSTATUS 43 55 ADDROVERRIDE 38 AMT 31 DoExpressCheckoutPayment 44 DoExpressCheckoutPayment response 48 GetTransactionDetails response 56 refunding 31 RefundTransaction 50 SetExpressCheckout 37 TransactionSearch 52 API certificate 10 16 API credentials 14 getting 10 setting up 11 API parameters 15 API Password 10 98 108 115 API signature 10 16 api sandbox paypal com 16 api 3t paypal com 16 api 3t sandbox paypal com 16 APlProfile interface
49. MBER Search by auction item number of the purchased goods No TRANSACTIONCLASS Search by classification of transaction No NOTE Some kinds of possible classes of transactions are not searchable with this field You cannot search for bank transfer withdrawals for example A11 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 e ECheck only transactions involving eCheck AMT Search by transaction amount No 52 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference al TransactionSearch TABLE A 12 TransactionSearch Request Parameters Continued Parameter Description Required STATUS
50. OCOUNTRYCODE Country code Character limit Two single byte characters For the list of country codes see Appendix F Country Codes SHIPTOZIP U S Zip code or other country specific postal code Character length and limitations 20 single byte characters ADDRESSSTATUS Status of street address on file with PayPal CUSTOM A free form field for your own use as set by you in the Custom element of SetExpressCheckout request Character length and limitations 256 single byte alphanumeric characters INVNUM Your own invoice or tracking number as set by you in the element of the same name in SetExpressCheckout request Character length and limitations 127 single byte alphanumeric characters PHONENUM Payer s contact telephone number NOTE PayPal returns a contact telephone number only if your Merchant account profile settings require that the buyer enter one Character length and limitations Field mask is XXX XXX XXXX for US numbers or XXX XXXXXXXX for international numbers REDIRECTREQUIRED If the value equals True you must redirect the user after the DoExpressCheckout call The value here indicates that you should inform your user on the Review Order page that he will be redirected to PayPal to complete the transaction DoExpressCheckoutPayment Request Request to obtain payment with PayPal Express Checkout IMPORTANT PayPal requires that a merchant using Express Checkout displa
51. PayPal Name Value Pair API Reference for Germany For Professional Use in Germany Only Currently only available in English A usage Professional en Allemagne uniquement Disponible en Anglais uniquement pour l instant Last updated April 2007 PayPal Name Value Pair API Developer Guide and Reference Document Number 100018 en_DE 20070410 2007 PayPal Inc All rights reserved PayPal is a registered trademark of PayPal Inc The PayPal logo is a trademark of PayPal Inc Other trademarks and brands are the property of their respective owners The information in this document belongs to PayPal Inc It may not be used reproduced or disclosed without the written approval of PayPal Inc PayPal Europe Ltd is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution PayPal FSA Register Number 226056 Notice of non liability PayPal Inc is providing the information in this document to you AS IS with all faults PayPal Inc makes no warranties of any kind whether express implied or statutory with respect to the information contained herein PayPal Inc assumes no liability for damages whether direct or indirect caused by errors or omissions or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein PayPal Inc reserves the right to make changes
52. Search and set the STAI RTDATI E field to the date you desire The date must be in UTC GMT format EXAMPLE 3 4 Searching for Transactions by STARTDATE requiredSecurityParameters sMETHOD TransactionSearch Request amp STARTDATE 2006 08 15T17 00 002 successResponseFields L_ TIMESTAMPO 2006 08 18T05 58 41Z TI EZONEO GMT L TYPEO Authorization amp L NAME0O John Doe amp LT NA amp L amp L amp L amp L TRANSACTIONIDO 3XK029742B016373C8L STATUSO Pending L AMTO 1 00 amp IMESTAMP1 2006 08 18T05 56 20Z26L TIMEZONE1 GMT amp L TYPE1 Payment E1 John Doe amp L TRANSACTIONID1 4BV19600WF261673U amp L STATUS1 Completed AMT1 1 00 amp L FEEAMT1 0 33 amp L NETAMT1 0 67 amp Li TIMESTAMP2 2006 08 18705 53 22Z amp L TIMEZONE2 GMT amp L TYPE2 Payment NAME2 John Doe amp L TRANSACTIONID2 6XB50622KC566325C amp L STATUS2 Completed L AMT2 1 00 amp L FEEAMT2 0 33 amp L NETAMT2 0 676 amp TIMESTAMP3 2006 08 18T05 38 04Z amp L TIMEZONE3 GMT TYPE3 Payment amp L NAME3 John Doe amp L TRANSACTIONID3 80774637LP956560E amp TATUS3 Completed amp L_ AMT3 1 00 amp L FEEAMT3 0 33 amp L NETAMT3 0 67 amp L TIMESTAMP4 2006 08 17T703 02 44Z amp L TIMEZONE4 GMT L TYPE4 Payment amp NAME4 Pettibonet Smythe Jon
53. TIONID 9JJ517146A732773R amp TRANSACTIONTYPE expresscheck out K PAYMENTTYPE instant amp ORDERT IME 2006 08 23T16 14 54Z amp AMT 10 00 amp CURRENCYCODE USD amp FEEAMT 0 59 amp TAXAMT 0 00 amp PAYMENTSTATUS Response Completed amp PENDINGREASON None amp REASONCODE None Updating the Shipping Address Using DoExpressCheckoutPayment You may need to update the shipping address on PayPal if the customer updates the shipping address after returning to your order review page If this happens you need to update the shipping address for this transaction on PayPal You can update the shipping address by setting the following parameters in DoExpressCheckoutPayment HI PTONAM EA HIPTOSTREET HIPTOSTREET2 PTOCITY HIPTOSTAT GI HI PTOCOUNTRYCOD El HI PTOPHONENUM e n n nn mam m wma L I HIPTOZIP 28 April 2007 Name Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout em Updating the Shipping Address Using DoExpressCheckoutPayment EXAMPLE 2 13 Updating the Shipping Address requiredSecurityParameters sMETHOD DoExpressCheckoutPayments METHOD DoExpressCheckoutPayment amp TOKEN EC 47C20533CU265432F amp PAYERID 95HR9CM6D5 6028 PAYMENTACTION SalesAMT 10 008 SHIPTONAME Mi chael Brown amp SHI PTOSTREET 22 First Street amp SHIPTOCITY Chicago amp Request SHIPTOCO
54. UMBERn 26 46 59 L OPTIONSn 59 H L QTY 46 L QTYn 26 46 59 L RECEIVERIDn 60 L STATUSn 53 L TAXAMTn 26 46 HANDLINGAMT 27 45 HDRBACKCOLOR 39 HDRBORDERCOLOR 39 do dd L TIMESTAMPn 53 Hong Kong Dollar 36 L_TIMEZONEn 53 ID HUF 36 L TRANSACTIONIDn 53 L TYPEn 53 L UNIQUEIDn 61 LASTNAME 42 52 55 LOCALECODE 39 log4j properties 105 log4net 111 logging levels 112 Hungarian Forint 36 IAPIProfile interface 114 IIS 116 Including a Note with the Refund 32 InstallSample bat 116 INVNUM 38 43 44 51 58 M ITEMAMT 27 45 MaseBay 115 MAXAMT 37 METHOD 15 124 March 2007 Name Value Pair API Developer Guide and Reference DoExpressCheckoutPayment 44 GetExpressCheckoutDetails 41 GetTransactionDetails 54 MassPay 60 RefundTransaction 50 SetExpressCheckout 36 TransactionSearch 51 Microsoft NET 1 1 109 MIDDLENAME 42 52 55 MULTIITEM 60 N NETREFUNDAMT 50 New Zealand Dollar 36 NOK 36 Norwegian Krone 36 NOSHIPPING 38 NOTE GetTransactionDetails response 58 RefundTransaction 50 NOTIFYURL 45 NVP format 12 posting 16 request creating and posting 11 interpreting 11 request format 14 request response model 12 response format 15 ACK values 16 error 16 NZD 36 O ORDERTIME 48 56 P PAGESTYLE 39 PARENTTRANSACTIONID 56 PASSWORD 59 PAYERBUSINESS 55 PAYERID 42 44 55 PAYERSTATUS 42 55 Name Value Pair API Developer Guide and Reference PAYFLOWCOLOR 39 PAYMENTACTION 37 44 PaymentAction 47 PA
55. UNTRYCODE US amp SHIPTOSTATE IL amp SHIPTOZIP 60605 successResponseFields sTOKEN EC 47C20533CU265432F amp TRANSACT IONID 5 913 958 4YA7 65250B amp TRANSACTIONTY PE expresscheckout amp PAYMENTTYPE instantsORDERTIME 2006 08 23T16 08 12Z8AMT 10 008 CURRENCYCODE USD amp FEEAMT 0 59 amp TAXAMT 0 00 amp PAYMENTSTATUS Completed amp Response PENDINGREASON None amp REASONCODE None Name Value Pair API Developer Guide and Reference April 2007 29 E Accepting PayPal in Express Checkout Updating the Shipping Address Using DoExpressCheckoutPayment 30 April 2007 Name Value Pair API Developer Guide and Reference Back Office Administration This section gives you examples of the following functions e Refunding Using RefundTransaction on page 31 e Searching for Transactions Using TransactionSearch on page 32 e Viewing Details of a Single Transaction Using GetTransactionDetails on page 33 Refunding Using RefundTransaction With RefundTransaction you can refund the full amount or a partial amount ofa transaction Specify the original transaction ID and the refund type Full or Partial Full Refund IMPORTANT If you refund the full amount do not set the AMT field EXAMPLE 3 1 Refunding the Full Amount of a Transaction requiredSecurityParameters METHOD Re fundTransaction amp TRANSACTIONID 01 9454569
56. YMENTSTATUS 49 57 PAYMENTTYPE 48 56 PayPal API servers API certificate 16 API signature 16 PayPal business account setting up 11 paypal tag in Web Config 111 PayPal supported currencies 35 Pending 57 Pending transaction status 53 PENDINGREASON 49 58 PendingReason 57 PERIOD 60 PHONENUM 40 43 PLN 36 Polish Zloty 36 Pound Sterling 35 Processed 57 Processing transaction status 53 ProfileFactory class 107 114 Profiles class 107 PWD 14 R REASONCODE 49 58 ReasonCode 57 REATTEMPT 59 RECEIPTID 51 56 RECEIVER 51 RECEIVERBUSINESS 54 RECEIVEREMAIL 54 RECEIVERID 54 RECEIVERTYPE 60 RECURRENCES 59 RECURRING 60 REDIRECTREQUIRED 43 49 Refunded 57 Refunding A Partial Amount 31 Refunding The Full Amount of a Transaction 31 RefundTransaction 31 107 115 REFUNDTRANSACTIONID 50 REFUNDTYPE 31 50 March 2007 125 Index REQCONFIRMSHIPPING 38 RETRYTIME 59 RETURNURL 36 Reversed 57 Reversed transaction status 53 S SALESTAX 58 SALUTATION 42 51 55 Sample API Certificate 108 116 sample API credentials 10 98 108 115 116 Sample API Signature 10 98 108 115 sample application 115 SampleApp 107 Sandbox 16 sdk seller p12 108 111 116 sdk seller apil sdk com 10 98 108 115 116 sdk three apil sdk com 10 98 108 115 security parameters required 14 SEK 36 servers PayPal API API certificate 16 API signature 16 Service Pack 1 for Microsoft NET Framework 1 1 110 SETTLEAMT 48 57 SGD 36 SHIPPING
57. a ed bee A A A 60 Appendix B Error Message Reference 63 Error Response Format varar kara 2 ra 63 Validation EMOS i a5 4 4 48 444 Sar a eek OH GRE GRE GE 63 General APLETfors ass gare de Bok g o eder E Grid gren ar Mr der an Ga 67 Express Checkout API Errors ka arken 68 RefundTransaction API Errors 2 aa arr akkar rann nn 84 TransactionSearch API Errors L 22222 arva aa aar kaka 87 GetTransactionDetails API Errors 00000 eee eee ee 89 MassPay API Errors a 89 Appendix C NVP API Web Samples 95 Descriptions of the Samples e 95 Accepting PayPal in Express Checkout ooa a a 95 Getting Transaction Details oa oaoa aaa ee 97 Common Files aoaaa a na 98 Sample API User with API Signature 0 kr kr ran 98 Samples Using PHP rrera eian iaa Sraa i unane 99 Required Software a a 99 Download and Unzip the Samples a 99 Installing the Samples csc ka ica ac ae RTT far ak ae eo ae REE E a 99 Running the Samples a 99 Samples Using Classic ASP 2 aar vr rar nn aa 100 Required Software 2 aar rv aars 100 Download and Unzip the Samples La aar vr rakk rn 100 Installing the Samples o krakk kran 100 Running the Samples a 100 Samples Using ColdFusion 2 2 2 a 101 Required Software
58. all Version number of the NVP API service Email address of a PayPal account that has granted you permission to Set this parameter only if you are calling an API on a different user s behalf IMPORTANT You must protect the values for USER PWD and SIGNATURE in your implementation Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user that executes your ecommerce application can access it The sample code does not store these values securely The sample code should never be used in production April 2007 Name Value Pair API Developer Guide and Reference Overview Technical Details cael You may see sample code where these values are stored in an HTML form The following is an example of what you should NOT do in production lt form method post action https api 3t sandbox paypal com nvp gt lt UNPROTECTED VALUES DO NOT USE IN PRODUCTION gt lt input type hidden name USER value xxxxxx paypal com gt lt input type hidden name PWD value abcdefg gt lt input type hidden name SIGNATURE value xXXXXXXXXXXXXXX gt lt form gt API Parameters The request body must contain the name of the API method in the METHOD parameter In addition each method has required and optional parameters METHOD methodName amp requiredAndOptionalParameters All API methods and their parameter
59. amples Samples Using ColdFusion 102 April 2007 Name Value Pair API Developer Guide and Reference The Java SDK This section describes how to use the Java SDK for the NVP API and includes the following topics e Installing the Java SDK on page 103 e Profiles on page 106 e Sample Applications on page 107 Installing the Java SDK This section details the software and hardware supported and required by the PayPal SDK installation and post installation tasks Supported Standards The PayPal SDK has been verified to work with the following standards TABLE D 1 Supported Standards Standard Version Java Runtime Environment 1 4 2 or greater Supported Human Languages The PayPal SDK is available in U S English SDK Version Number This guide describes PayPal Java SDK version 5 1 1 Name Value Pair API Developer Guide and Reference April 2007 103 el The Java SDK Installing the Java SDK Recommended Hardware Configuration The minimum hardware requirements for using the PayPal SDK in development and test are listed below Production systems might require more capacity depending on their expected load TABLE D 2 Recommended Hardware Configuration Component Minimum Capacity RAM 256 MB CPU Pentium I GHz Disk space 50 MB Download and Unzip the SDK The latest version of the PayPal SDK is available at https www paypal com IntegrationCenter ic nvp html 1 Download the zipfile dis
60. ates the IAPIProfile object It contains static methods that handle the instantiation and construction of profile objects EWPProfile interface This interface defines the basic information that PayPal needs to know about a user of PayPal s Encrypted Website Payments EWP service Developers must create an instance of EWPProfile for each account that generates the encrypted button code for single merchant users this will just be a single instance PayPal provides a basic implementation class called DefaultE WPProfile suitable for the needs of most SDK developers However you are free to write a custom implementation if you need functionality the default class does not offer 114 April 2007 Name Value Pair API Developer Guide and Reference The ASP NET SDK Sample Applications ad Sample Applications The PayPal SDK includes sample applications in the SDK root samples VASPNET folder The samples VASPNET folder is divided into subfolders by products TABLE E 6 Samples by Product Subfolder in SDK_Root samples ASPNET Products GetTransactionDetails MassPay RefundTransaction TransactionSearch wppro Express Checkout Sample API User with API Signature The samples come with an API signature for use with the samples and the PayPal Sandbox This API signature belongs to the following user TABLE E 7 Details of the Sample API Signature API username sdk three apil sdk com API password QFZCWNSHZM8VBG70
61. ating the Shipping Address Using DoExpressCheckoutPayment 28 Chapter 3 Back Office Administration 4 31 Refunding Using RefundTransaction 2 000000 ee eee 31 Full Refund 31 Partial Refunds R e o e N Kd ee 31 Including a Note with the Refund 0 0020 eo 32 Searching for Transactions Using TransactionSearch 0 32 Viewing Details of a Single Transaction Using GetTransactionDetails 33 Appendix A NVP API Method and Field Reference 2 2 222235 General Characteristics of Requests and Parameters 2 222 arv 35 Parameters sans da sir et San ae ed mr gm ek an BS 35 Multi Value Fields ee 35 PayPal Supported Transactional Currencies 24 35 Express Checkout 222 aa rava ee 36 SetExpressCheckout Request 0 000022 ee eee eee 36 SetExpressCheckout Response 220 200 an 41 GetExpressCheckoutDetails Request 2 00 022007 41 GetExpressCheckoutDetails Response 002 5200 42 DoExpressCheckoutPayment Request e o 43 DoExpressCheckoutPayment Response rar ark naa 47 4 April 2007 Name Value Pair API Developer Guide and Reference Contents L RefundTransaction 2 2 aka 50 TransactionSearch 2 rava rank akkar 50 GetTransactionDetails a oa a a a 54 Mass Payment 2 ewa d dd a a
62. by setting the NOTIFYURL parameter in DoExpressCheckoutPayment NoTE If you do not specify this value in the request the notification URL from your Merchant Profile is used if one exists For more information about IPN see the Order Management Integration Guide EXAMPLE 2 9 Changing the URL for IPN frequiredSecurityParametersjsMETHOD DoExpressCheckoutPayment amp TOKEN EC 8AX1275942659774U amp PAYERI D 95HR9CM6D5 602 amp AMT 10 00 amp Request PAYMENTACTION Sale amp NOTIFYURL https www anycompany com process ipn Name Value Pair API Developer Guide and Reference April 2007 25 A Accepting PayPal in Express Checkout Including Line Item Details Using DoExpressCheckoutPayment Response successResponseFields sTOKEN EC 8AX1275942659774U amp TRANSACTIONID 1MA55216691247718 amp TRANSACTIONTY PE expresscheckout amp PAYMENTTYPE instant ORDERT IME 2006 08 22T22 39 13Z amp AMT 10 00 amp CURRENCYCODE USD amp FEEAMT 0 59 amp TAXAMT 0 00 amp PAYMENTSTATUS Completed amp PENDINGREASON None amp REASONCODE None Including Line Item Details Using DoExpressCheckoutPayment You can include line item details by setting the following parameters in DoExpressCheckoutPayment L_NAMEn item name or description L NUMBER line item number L QTYn item quantity L TAXAMTn sales tax for the item L_AMTn
63. ck to PayPal This error occurs if at Integration Point 1 you set PaymentAction to Sale with SetExpressCheckout request but at Integration Point 3 you set PaymentAction to Authorization with DoExpressCheckout Payment PayPal does not allow this switch from Sale to Authorization in a single checkout session PayPal does allow the reverse however You can set PaymentAction to Authorization with SetExpressCheckout at Integration Point 1 and switch PaymentAction to Sale with DoExpressCheckoutPayment at Integration Point 3 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 For the rules of this calculation see the chapter about best practices in the PayPal Express Checkout Integration Guide 80 March 2007 Name Value Pair API Developer Guide and Reference TABLE B 5 DoExpressCheckoutPayment API Errors Error Message Reference Express Checkout API Errors Error Code 10431 10432 10433 10434 10435 10441 Short Message Ttem amount is invalid Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See a
64. cters SHIPTOSTREET2 Second street address No Character length and limitations 100 single byte characters PHONENUM Phone number No Character length and limit 20 single byte characters 40 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout SetExpressCheckout Response TABLE A 4 SetExpressCheckout Response Fields Parameter Description TOKEN A timestamped token by which you identify to PayPal that you are processing this payment with Express Checkout NOTE The token expires after three hours If you set the token in the SetExpressCheckout request the value of the token in the response is identical to the value in the request Character length and limitations 20 single byte characters Redirecting the Customer s Browser to PayPal Login Page After you receive a successful response from SetExpressCheckout add the TOKEN from SetExpressCheckout response as a name value pair to the following URL and redirect your customer s browser to it https www paypal com cgi bin webscr cmd express checkout token value from SetExpressCheckoutRespons For redirecting the customer s browser to the PayPal login page PayPal recommends that you use the HTTPS response 302 Object Moved with the URL above as the value of the Location header in the HTTPS response Ensure that you use an SSL enabled server to prevent browser warning
65. date is invalid of an invalid argument See additional error messages for details 10004 Transaction refused because Currency is not supported of an invalid argument See additional error messages for details 10004 Transaction refused because Transaction class is not supported of an invalid argument See additional error messages for details 10004 Transaction refused because Receipt id is not valid of an invalid argument See additional error messages for details 10004 Transaction refused because Payer email is invalid of an invalid argument See additional error messages for details 10004 Transaction refused because Auction item id is not valid of an invalid argument See additional error messages for details 10004 Transaction refused because Receiver email is invalid of an invalid argument See additional error messages for details 10004 Transaction refused because You can not search for a transaction id and a receipt id of an invalid argument See additional error messages for details 10004 Transaction refused because Receiver can only be specified for payments you ve received of an invalid argument See additional error messages for details 88 March 2007 Name Value Pair API Developer Guide and Reference Error Message Reference GetTransactionDetails API Errors I TABLE B 2 TransactionSearch API Errors Error Code Short Message Long Message 10004 Transaction refused because The transaction id
66. dditional 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 Item amount is invalid Invoice ID value exceeds maximum allowable length Value of OrderDescription element has been truncated Value of Custom element has been truncated The customer has not yet confirmed payment for this Express Checkout session The NotifyURL element value exceeds maximum allowable length Correcting This Error Name Value Pair API Developer Guide and Reference March 2007 81 Error Message Reference Express Checkout API Errors TABLE B 5 DoExpressCheckoutPayment API Errors 82 Error Short Code Message Long Message Correcting This Error 10442 ButtonSource The ButtonSource element value value exceeds maximum allowable truncated length 10443 Transaction This transaction cannot be refused completed with PaymentAction because ofan of Order invalid argument See additional error messages for details 10444 Transaction The transaction currency refused specified must be the same as because ofan previously specified invalid argument See additional error messages for details 10445 This This transaction ca
67. dress are described in Table A 8 Optional Ship to Address IMPORTANT Ship to Address is optional but if you include it certain fields are required Required No No TABLE A 8 Optional Ship to Address Parameter SHIPTONAME SHIPTOSTREE SHIPTOCITY Description Person s name associated with this address Character length and limitations 32 single byte characters First street address Character length and limitations 100 single byte characters Name of city Character length and limitations 40 single byte characters Required Yes Yes Yes 46 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout L TABLE A 8 Optional Ship to Address Continued Parameter Description Required SHIPTOSTATE State or province Yes Character length and limitations 40 single byte characters SHIPTOCOUNTRYCODE Country code Yes Character limit Two single byte characters For the list of country codes see Appendix F Country Codes SHIPTOZIP U S ZIP code or other country specific postal code Yes Character length and limitations 20 single byte characters SHIPTOSTREET2 Second street address No Character length and limitations 100 single byte characters SHIPTOPHONENUM Phone number No Character length and limit 20 single byte characters DoExpressCheckoutPayment Response TABLE
68. e This page displays a text box where the user enters a transaction ID and a Submit button that calls TransactionDetails ext Calls TransactionDetails ext TransactionDetails ext Sends a Get TransactionDetails NVP API request to PayPal The code retrieves the transaction ID and constructs the NVP API request string to send to the PayPal server The request to PayPal uses an API signature After receiving the response from the PayPal server the code displays the request and response in the browser If the response was a success it displays the response parameters If the response was an error it displays the errors received Called by GetTransactionDetails html Name Value Pair API Developer Guide and Reference April 2007 97 i NVP API Web Samples Common Files The following files are common to the samples TABLE C 3 Common Files File Description index html The main web page with links to each sample Default htm Calls SetExpressCheckout ext and GetTransactionDetails html sdk css Cascading Style Sheet CSS used by index html or Default htm CallerService ext This is the configuration file for the samples This file contains the parameters needed to make an API call The samples come with an API signature for making API calls to the PayPal sandbox The API signature is described in Sample API User with API Signature on page 98 Called by TransactionDetails ext ReviewOrder ext and Display ext Display ext Disp
69. e 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 Name Value Pair API Developer Guide and Reference April 2007 Revision History Revision History Revision history for PayPal Name Value Pair API Developer Guide and Reference TABLE P 1 Revision History Date Description April 2007 Revised document to represent specifics for Germany February 2007 Bug fixes including updating Line Item Details for Express Checkout APIs dding SHIPTOCOUNTRYCODE and adding Switch Solo codes for AVS and CVV2 December 2006 Updates for bug fixes October 2006 First public release 8 April 2007 Name Value Pair API Developer Guide and Reference Overview This chapter describes the PayPal Name Value Pair NVP API at a high level and contains the following sections e Introducing the PayPal NVP API e Basic Steps e Taking Your Application Live e Technical Details Introducing the PayPal NVP API The PayPal NVP API is a simple programmatic interface that allows you the merchant to access PayPal s business functionality to e Accept PayPal in checkout on your website using Express Checkout e Pay one or more recipients using Mass Payment e Issue full refunds or multiple partial refunds e Search transactions using a start date or other criteria e View details of a specific transaction The PayPal NVP API
70. e Postal Code Long Message Payment declined by your Risk Controls settings PayPal Risk Model There was an error in the Shipping Address Country field The field Shipping Address 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 Correcting This Error Name Value Pair API Developer Guide and Reference March 2007 83 Error Message Reference RefundTransaction API Errors RefundTransaction API Errors TABLE B 6 Refund Transaction API Errors Short Error Code Message 10001 10001 Internal Error Internal Error 10001 ButtonSource value truncated 10001 10004 Internal Error Transaction refused because of an invalid argument See additional error messages for details 10004 Transaction refused because of an invalid argument See additional error messages for details 10004 Transaction refused because of an invalid argument See additional error 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 pa
71. e using API certificates the path to the API certificate in P12 format and the private key password to that certificate e Ifyou are using API signatures the signature string e The optional name of a third party who authorizes the caller to invoke PayPal APIs on his behalf This third party is called a subject e The PayPal environment for processing API calls live or sandbox An EWP profile is associated with EWP Services includes e The path to the merchant s local copy of that public certificate e The private key password for that public certificate e The path to a merchant s private key file for digitally signing data e The URL to which the button form POSTs e The optional URL of a payment button image The default is PayPal s standard Buy Now button For more information about how EWP works see the Website Payments Standard Integration Guide available at https www paypal com en_US pdf PP_WebsitePaymentsStandard_IntegrationGuide pdf Overview to Profile related Classes The primary interfaces and classes for SDK profiles are described in Table D 5 Interface and Classes for SDK Profiles on page 106 TABLE D 5 Interface and Classes for SDK Profiles Interface Class Descriptions APIProfile interface This interface defines the basic information that PayPal needs to know about a user of the PayPal Web Service APIs Developers must create an instance of APIProfile for each account that accesses the APIs For si
72. ed call 10009 Transaction You do not have a verified ACH refused 10009 Transaction The partial refund amount must be less than or refused equal to the original transaction amount 10009 Transaction The partial refund amount must be less than or refused equal to the remaining amount 10009 Transaction The partial refund amount is not valid refused 10009 Transaction Because a complaint case exists on this refused transaction only a refund of the full or full remaining amount of the transaction can be issued 10009 Transaction You are over the time limit to perform a refund refused on this transaction 10009 Transaction Can not do a full refund after a partial refund refused 10009 Transaction Account is locked or inactive refused 10009 Transaction The partial refund must be the same currency refused as the original transaction 10009 Transaction This transaction has already been fully refused refunded Correcting This Error 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 March 2007 Name Value Pair API Developer Guide and Reference Error Message Reference TransactionSearch
73. effect of setting other elements is additive or can alter the search criteria 50 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference TransactionSearch al TransactionSearch returns up to 100 matches Partial matches are displayed For example setting the TransactionSearchRequest FirstName to Jess returns results such as Jessica and Jesse The most important returned element is TransactionID which you can pass to GetTransactionDetails in order to retrieve all available information about a specific transaction TABLE A 12 TransactionSearch Request Parameters Parameter Description Required METHOD Name of API call TransactionSearch Yes STARTDATE The earliest transaction date at which to start the search 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 No EMAIL Search by the buyer s email address No Character length and limitations 127 single byte alphanumeric characters RECEIVER Search by the receiver s email address If the merchant account has only No one email this is the primary email Can also be a non primary email RECEIPTID Search by the PayPal Account Optional receipt ID No TRANSACTIONID Search by the transaction ID No NOTE The returned results are from the merchant s transaction records Character length and li
74. ent Type which becomes the value of the PAYMENTACTION parameter When the user clicks the Submit button ReviewOrder ext is called Called by index html or Default htm Calls ReviewOrder ext This file is called after the user clicks on a button during the checkout process to use PayPal s Express Checkout The user logs in to their PayPal account This file is called twice On the first pass the code executes the if statement if isset Stoken The code collects transaction parameters from the form displayed by SetExpressCheckout ext then constructs and sends a SetExpressCheckout request string to the PayPal server The paymentType variable becomes the PAYMENTACTION parameter of the request string The RETURNURL parameter Is set to this file this is how ReviewOrder ext is called twice On the second pass the code executes the else statement On the first pass the buyer completed the authorization in their PayPal account now the code gets the payer details by sending a GetExpressCheckoutDetails request to the PayPal server Then the code calls GetExpressCheckoutDetails ext NOTE Be sure to check the value of PAYPAL URL The buyer is sent to this URL to authorize payment with their PayPal account For testing purposes this should be set to the PayPal sandbox Called by SetExpressCheckout ext Calls GetExpressCheckoutDetails ext CallerService ext and Display ext This functionality is called after
75. er e guarantee A reversal has occurred on this transaction due to your customer triggering a money back guarantee e buyer complaint A reversal has occurred on this transaction due to a complaint about the transaction from your customer e refund A reversal has occurred on this transaction because you have given the customer a refund e other A reversal has occurred on this transaction due to a reason not listed above E REASONCOD INVNUM Invoice number you set in the original transaction Character length and limitations 127 single byte alphanumeric characters CUSTOM Custom field you set in the original transaction Character length and limitations 127 single byte alphanumeric characters NOT Memo entered by your customer in PayPal Website Payments note field E Character length and limitations 255 single byte alphanumeric characters SALESTAX Amount of tax charged on payment 58 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference GetTransactionDetails ul TABLE A 15 GetTransactionDetails Response Fields Continued Parameter Description L DESCn 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 These paramet
76. er s first name Character length and limitations 25 single byte characters MIDDLENAME Payer s middle name Character length and limitations 25 single byte characters LASTNAME Payer s last name Character length and limitations 25 single byte characters SUFFIX Payer s suffix Character length and limitations 12 single byte characters COUNTRYCODE Payer s country of residence in the form of ISO standard 3166 two character country codes Character length and limitations Two single byte characters For the list of country codes see Appendix F Country Codes BUSINESS Payer s business name Character length and limitations 127 single byte characters SHIPTONAME Person s name associated with this address Character length and limitations 32 single byte characters SHIPTOSTREET First street address Character length and limitations 100 single byte characters 42 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout a TABLE A 6 GetExpressCheckoutDetails Response Fields Continued Field Description SHIPTOSTREET2 Second street address Character length and limitations 100 single byte characters SHIPTOCITY Name of city Character length and limitations 40 single byte characters SHIPTOSTATE State or province Character length and limitations 40 single byte characters SHIPT
77. er HTML hexadecimal color code in ASCII PAYFLOWCOLOR Sets the background color for the payment page No Character length and limitation Six character HTML hexadecimal color code in ASCII Name Value Pair API Developer Guide and Reference April 2007 39 el NVP API Method and Field Reference Express Checkout TABLE A 2 SetExpressCheckout Request Parameters Continued Parameter Description Required Shipping Address Optional shipping address The parameters for the optional Ship to No Address are described in Table A 3 Ship to Address Optional IMPORTANT Ship to Address is optional but if you include it certain fields are required TABLE A 3 Ship to Address Optional Parameter Description Required SHIPTONAME Person s name associated with this shipping address Yes Character length and limitations 32 single byte characters SHIPTOSTREET First street address Yes Character length and limitations 100 single byte characters SHIPTOCITY Name of city Yes Character length and limitations 40 single byte characters SHIPTOSTATE State or province Yes Character length and limitations 40 single byte characters SHIPTOCOUNTRYCODE Country code Yes Character limit Two single byte characters For the list of country codes see Appendix F Country Codes SHIPTOZIP U S Zip code or other country specific postal code Yes Character length and limitations 20 single byte chara
78. ers should be ordered sequentially beginning with 0 for example L DESCO L DESC1 and so forth L_NUMBERn Item number set by you If this was a shopping cart transaction PayPal appends the number of the item to the HTML item number variable For example item numberl item number2 and so forth Character length and limitations 127 single byte alphanumeric characters These parameters should be ordered sequentially beginning with 0 for example L NUMBERO L_NUMBER1 and so forth L OTYn Quantity set by you or entered by the customer Character length and limitations no limit These parameters should be ordered sequentially beginning with 0 for example L QTYO L QTY1 and so forth L AMTn Cost of item These parameters should be ordered sequentially beginning with 0 for example L AMTO L AMTI1 and so forth L OPTIONSn PayPal item options for shopping cart These parameters should be ordered sequentially beginning with 0 for example L OPTIONSO L OPTIONS1 and so forth SUBSCRIPTIONID ID generated by PayPal for the subscriber Character length and limitations no limit SUBSCRIPTIONDATE Subscription start date EFFECTIVEDATE Date when the subscription modification will be effective RETRYTIME Date PayPal will retry a failed subscription payment USERNAME Username generated by PayPal and given to subscriber to access the subscription Character length and limitat
79. ert and accept this payment You must manually accept or deny this payment e verify The payment is pending because you are not yet verified You must verify your account before you can accept this payment e other The payment is pending for a reason other than those listed above For more information contact PayPal customer service ral REASONCODE The reason for a reversal if TransactionType Is reversal e none No reason code e chargeback A reversal has occurred on this transaction due to a chargeback by your customer e guarantee A reversal has occurred on this transaction due to your customer triggering a money back guarantee e buyer complaint A reversal has occurred on this transaction due to a complaint about the transaction from your customer e refund A reversal has occurred on this transaction because you have given the customer a refund e other A reversal has occurred on this transaction due to a reason not listed above REDIRECTREQUIRED Ifthe value equals True you have to redirect the user to PayPal PayPal will direct the user according to the selected payment methods e g to giropay When redirecting the user to Paypal you need to append the Token value to the following redirect URL https www paypal com webscr cmd complete express checkout amp token TOKEN TOKEN needs to equal the Token value that you received in the SetExpressCheckoutResponse Name Value Pair AP
80. es amp L TRANSACTIONID4 8640321568512733L amp Respons L STATUS4 Completed amp l AMT4 104 00 amp L FEEAMT4 3 32 amp L NETAMT4 100 68 TransactionSearch returns a multi valued array of all transactions that match the search criteria Each transaction begins with its date L_TIMESTAMPn where n starts with 0 and increments by one for each transaction 32 April 2007 Name Value Pair API Developer Guide and Reference Back Office Administration E Viewing Details of a Single Transaction Using GetTransactionDetails Viewing Details of a Single Transaction Using GetTransactionDetails To view all details about a single transaction use GetTransactionDetalls EXAMPLE 3 5 Viewing A Transaction s Details requiredSecurityParameters sMETHOD GetTransactionDetails Request amp TRANSACTIONID 3B288546P5019992D successResponseFields RECEIVERBUS INESS Jims Hardware amp RECEIVEREMAIL 3 im hardwareplace com amp RECEIVERID WNSJNN8 9XVWFA amp PAYERID B3KS3VFYNG9SN amp PAYERSTATUS unveri fied amp FIRSTNAME James amp LASTNAME Biguy amp COUNTRYCODE US amp SHIPTOSTATE amp ADDRESSID PayPal amp ADDRESSSTATUS None amp TRANSACTIONID 3B288546P5019992D amp RECEIPTID 3596 6202 14612615 amp TRANSACT IONTYPE webaccept amp PAYMENTTYPE instant amp ORDERTIME 2006 08 15T17 00 00Z amp AMT 127 87 amp CURRENCYCODE USD amp FEEAMT 4 01 Response TAXAMT 0 00 amp PENDINGREASON None amp REASON
81. essCheckoutPayment API Errors Error Code 10421 10422 10423 10424 Short Message Long Message This Express Checkout session belongs to a different customer Token value mismatch This Express Checkout session belongs to a different customer The customer must return to PayPal to select new funding sources Customer must choose new funding sources This transaction cannot be completed with PaymentAction of Authorization Transaction refused because of an invalid argument See additional error messages for details Transaction Shipping address is invalid refused because of an invalid argument See additional error messages for details Correcting This Error When your customer logs into PayPal the PayPal PayerTDis associated with the Express Checkout token This error is caused by mixing tokens for two different PayerTDs The Token and PayerID returned for any particular customer by GetExpressCheckoutDetails response must be the same ones you send with DoExpressCheckout Payment Verify that your programs are properly associating the Tokens and PayerTDs It is possible that the payment method the customer chooses on PayPal might not succeed when you send DoExpressCheckoutPayment request If the customer has a different PayPal funding source that is likely to succeed DoExpressCheckout Payment response returns error code 10422 so you can redirect the customer ba
82. etails Specifying Logo and Color Settings Individually You can modify the PayPal web pages to look like your own web pages by setting the following parameters in SetExpressCheckout e HDRIMG specify an image to appear at the top left of the payment page e HDRBORDERCOLOR set the border color around the header of the payment page e HDRBACKCOLOR set the background color for the background of the header of the payment page e PAYFLOWCOLOR set the background color for the payment page EXAMPLE 2 7 Specifying Logo and Color Settings Individually requiredSecurityParameters METHOD SetExpressCheckoutsAMT 10 008 RETURNURL https ww anycompany com orderprocessing orderreview htmlg CANCELURL https ww anycompany com orderprocessing shippinginfo htmlg HDRIMG https www anycompany com images HeaderImage gif amp Request HDRBORDERCOLOR 336 6F F 4HDRBACKCOLOR D3EFF 5 amp PAYFLOWCOLOR F8F5F5 Response successResponseFields TOKEN EC 17C76533PL706494P Form Filling Your Payment Review Page Using GetExpressCheckoutDetails Use the payer name and shipping address returned by GetExpressCheckoutDetails response to fill in form fields on your payment review page which you display after the customer returns from PayPal EXAMPLE 2 8 Form Filling Your Payment Review Page frequiredSecurityParametersjsMETHOD GetExpressCheckoutDetails amp Request TOKEN EC 3DJ780
83. etting you have specified in your Merchant Account Profile Character length and limitations One single byte numeric character Allowable values 0 1 Default 0 NOSHIPPING The value 1 indicates that on the PayPal pages no shipping address No fields should be displayed whatsoever Character length and limitations Four single byte numeric character Allowable values 0 1 Default 0 ADDROVERRIDE The value 1 indicates that the PayPal pages should display the No shipping address set by you in this SetExpressCheckout request 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 Allowable values 0 I Default 0 TOKEN A timestamped token by which you identify to PayPal that you are No processing this payment with Express Checkout NOTE The token expires after three hours If you set the token in the SetExpressCheckout request the value of the token in the response is identical to the value in the request Character length and limitations 20 single byte characters Allowable values See the description of TOKEN in Table A 4 SetExpressCheckout Response Fields 38 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout TABLE A 2 SetExpressCheckout Request Parameters Continued Parameter Description Required
84. ew html amp CANCELURL https www anycompany com orderprocessing shippinginfo html Request amp LOCALECODE fr FR Response successResponseFields sTOKEN EC 17C76533PL706494P Changing the Logo on the PayPal Pages Using SetExpressCheckout You can modify the logo and other color settings on the PayPal pages in two ways e Specifying a predefined Custom Payment Page Style e Setting logo and color settings individually Specifying a Custom Payment Page Style You can set the Custom Payment Page Style for the PayPal pages by setting the PAGESTYLE parameter in SetExpressCheckout Set PAGESTYLE to one of the Page Style Names you defined in your Custom Payment Pages on https www paypal com The following example sets PAGESTYLE to DesignerFotos Yel low in the SetExpressCheckout method EXAMPLE 2 6 Specifying a Custom Payment Page Style requiredSecurityParameters METHOD SetExpressCheckout amp AMT 10 008 RETURNURL https ww anycompany com orderprocessing orderreview htmlg CANCELURL https ww anycompany com orderprocessing shippinginfo htmlg Request PAGESTYLE DesignerFotos Yellow Response successResponseFields sTOKEN EC 17C76533PL706494P Name Value Pair API Developer Guide and Reference April 2007 23 Fe Accepting PayPal in Express Checkout Form Filling Your Payment Review Page Using GetExpressCheckoutD
85. g applications with the SDK be sure to add references in your ASP NET projects to the SDK dynamic load libraries DLLs in SDK_root bin Installing the Samples The SDK comes with sample applications for your study and use These samples can be installed in Microsoft Internet Information Server IIS For more information about the samples see Sample Applications on page 115 For more information about installing in IIS see Installing the Samples in IIS on page 116 110 April 2007 Name Value Pair API Developer Guide and Reference The ASP NET SDK Installing the ASP NET SDK The SDK components are organized into different subdirectories as shown in Table E 3 PayPal SDK Directories and Contents SDK Directories and Optional Configurations TABLE E 3 PayPal SDK Directories and Contents Directory Descrption bin Compiled SDK DLLs docs Ndoc class documentation and SDK guide samples ASPNET Example code that use the SDK in subdirectories samples cert sdk seller p12 API certificate for API user sdk seller apil sdk com src Visual Studio project files and SDK source files This folder is present only if you installed the source of the SDK Optional Custom Configurations in Web config You can add optional custom settings to the Web config file Adding PayPal Settings First add a lt section name paypal gt tag as shown below The section must be enclosed in lt configSections gt that come
86. h the following standards TABLE E 1 Supported Standards Standard Version Microsoft NET Framework 1 1 Service Pack 1 Supported Human Languages The PayPal SDK is available in U S English SDK Version Number This guide describes PayPal ASP NET SDK version 5 1 1 Name Value Pair API Developer Guide and Reference April 2007 109 The ASP NET SDK Installing the ASP NET SDK Minimum Hardware Requirements The following table lists the minimum hardware requirements for using the PayPal SDK in development and test Production systems might require more capacity depending on their expected load TABLE E 2 Minimum System Hardware Requirements Component Minimum Capacity RAM 256 MB CPU Pentium 1 GHz Disk space 50 MB Required Microsoft NET Framework 1 1 Service Pack 1 IMPORTANT The PayPal SDK requires Service Pack 1 for Microsoft NET Framework 1 1 You can get Service Pack 1 from the Microsoft web site Downloading and Installing the SDK The latest version of the PayPal SDK is available at https www paypal com IntegrationCenter ic_nvp html You can download either a self extracting installation program or a zipfile distribution The installation is straightforward and requires no special instruction You have the option to install the SDK source if you like Post installation Set up This section details steps to take before you start using the PayPal SDK Referencing the SDK DLLs Before developin
87. haracters SHIPTOPHONENUM Phone number associated with this address SHIPTOZIP Postal code Name Value Pair API Developer Guide and Reference April 2007 55 EA NVP API Method and Field Reference GetTransactionDetails TABLE A 15 GetTransactionDetails Response Fields Continued Parameter SHIPTOSTAT E SHIPTOSTREET SHIPTOSTREET2 PARENTTRANSACTIONID TRANSACTIONID RECEIPTID TRANSACTIONTYP FI PAYMENTTYPE ORDERTIME Description State or province Character length and limitations 120 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 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 ParentTransactionIDis the original OrderID e Authorization of an order The value of ParentTransactionID is the original OrderTD e Capture of an order authorization e Void of an order The value of ParentTransaction1lD is the original OrderID Character length and limitations 19 single byte characters PayPal transaction identification number Character length and limitations 19 s
88. ingle 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 the 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 Indicates whether the payment is instant or delayed Character length and limitations Seven single byte characters Date and time of payment Full amount of the customer s payment before transaction fee is subtracted 56 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference GetTransactionDetails ul TABLE A 15 GetTransactionDetails Response Fields Continued Parameter Description FEEAMT Transaction fee associated with the payment SETTLEAMT Amount deposited into the account s primary balance after a currency conversion from automatic conversion through your Payment Receiving Preferences or manual conversion through manually accepting a payment This amount is calculated after fees and taxes have been assessed
89. install and configure PHP with the Apache HTTP Server Download and Unzip the Samples The latest version of the Web Samples are available at https www paypal com IntegrationCenter ic nvp html 1 Download the zipfile distribution 2 Unzip the zipfile to any directory of you choose Installing the Samples Copy the sample folder php nvp samples to the docroot of the Apache HTTP Server By default docroot is in datadir htdocs Running the Samples First make sure that you have installed the required software and the samples You can run the samples by entering the following address in a web browser http name of Apache HTTP Server port php nvp samples index html Name Value Pair API Developer Guide and Reference April 2007 99 NVP API Web Samples Samples Using Classic ASP Samples Using Classic ASP This section contains information for configuring and running the NVP API Web Samples Using Classic ASP Required Software No additional software is required Download and Unzip the Samples The latest version of the Web Samples are available at https www paypal com IntegrationCenter ic_nvp html 1 Download the zipfile distribution 2 Unzip the zipfile to any directory of you choose Installing the Samples The samples must be installed in IIS The samples require IIS version 5 1 or above Create a virtual directory named PayPalClassicAspNvpSamples in IIS that points to Samples Root Running the
90. ion id is not valid refused because of an invalid argument See additional error messages for details Name Value Pair API Developer Guide and Reference March 2007 75 ME Error Message Reference Express Checkout API Errors TABLE B 4 GetExpressCheckoutDetails API Errors Error Short Code Message Long Message Correcting This Error 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 is 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 B 5 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 10001 ButtonSource The transaction could not be value loaded truncated 10001 Internal Error Internal Error 76 March 2007 Name Value Pair API Developer Guide and Reference TABLE B 5 DoExpressCheckoutPa
91. ions 64 alphanumeric single byte characters PASSWORD 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 alphanumeric single byte characters RECURRENCES The number of payment installments that will occur at the regular rate Character length and limitations no limit REATTEMPT Indicates whether reattempts should occur upon payment failures Name Value Pair API Developer Guide and Reference April 2007 59 i NVP API Method and Field Reference Mass Payment TABLE A 15 GetTransactionDetails Response Fields Continued Parameter Description RECURRING Indicates whether regular rate recurs 1 Yes PERIOD The period of time that the subscriber will be charged Character length and limitations no limit BUYERID Customer s auction ID CLOSINGDATE Auction s close date MULTIITEM Counter used for multi item auction payments Mass Payment TABLE A 16 MassPay Parameters Require Parameter Description d METHOD Name of the API MassPay Yes RECEIVERTYPE Indicates how you identify the recipients of payments in all the individual Yes mass payment items either by EmailAddress L_EMATLn in the individual item or by UserID L RECEIVERI
92. l com nvp API Servers for API Certificate Security If you use an API certificate post the request to one of these servers Sandbox https api sandbox paypal com nvp Live https api paypal com nvp 16 April 2007 Name Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout By choosing Express Checkout the customer can save time by skipping several checkout steps using the billing and shipping information stored on PayPal This section describes how to use Express Checkout to accept payments using PayPal and contains the following topics e Basic Checkout with PayPal on page 17 e Controlling the Shipping Address Using SetExpressCheckout on page 21 e Changing the Language on the PayPal Login Page Using SetExpressCheckout on page 23 e Changing the Logo on the PayPal Pages Using SetExpressCheckout on page 23 e Form Filling Your Payment Review Page Using GetExpressCheckoutDetails on page 24 e Making a Sale Using DoExpressCheckoutPayment on page 25 e Changing the URL for IPN Using DoExpressCheckoutPayment on page 25 e Including Line Item Details Using DoExpressCheckoutPayment on page 26 e Including Subtotals Using DoExpressCheckoutPayment on page 27 e Updating Order Details Using DoExpressCheckoutPayment on page 27 e Updating the Shipping Address Using DoExpressCheckoutPayment on page 28 Basic Checkout with PayPal NOTE See the In
93. l shipping costs for this order No NOTE 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 optional thousands separator must be a comma Equivalent to nine characters maximum for USD HANDLINGAMT Total handling costs for this order No NOTE 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 optional thousands separator must be a comma Equivalent to nine characters maximum for USD TAXAMT Sum of tax for all items in this order No NOTE 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 optional thousands separator must be a comma Equivalent to nine characters maximum for USD NOTE TAXAMT is required if you specify a value for L_TAXAMTn CURRENCYCODE A three character currency code for one of the currencies listed in PayPal No Supported Transactional Currencies Default USD L NAMEN Item name No Character length and limitations 127 single byte characters These parameters should be ordered sequentially beginning with 0 for example L NAMEO L_NAME1 and so forth Name Value Pair API Developer Guide and Reference April 2007 45
94. lays request and response parameters If there is an error displays request and error parameters Called by TransactionDetails ext and DoExpressCheckoutPayment ext Sample API User with API Signature The samples come with an API signature for use with the samples and the PayPal Sandbox This API signature belongs to the following user TABLE C 1 Details of the Sample API Signature API username sdk three apil sdk com API password QFZCWNSHZM8VBG70 API signature A IzJhZZjhg29XQ02qnhapuwxIDzyAZQ92FRP5dq9BzVesOkzbdUONzZmOU IMPORTANT You must protect the API signature values in your implementation Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it The sample code does not store these values securely The sample code should never be used in production 98 April 2007 Name Value Pair API Developer Guide and Reference NVP API Web Samples Samples Using PHP mn Samples Using PHP This section contains information for configuring and running the NVP API Web Samples Using PHP Required Software The following software is required TABLE C 4 Required Software Software Version Download Location PHP with CURL extension 4 4 2 or greater http www php net downloads php enabled Apache HTTP Server 1 3 17 or greater http httpd apache org You must
95. length and limitations 4 000 single byte alphanumeric characters These parameters should be ordered sequentially beginning with 0 for example L NOTEO L_NOTE1 and so forth EMAILSUBJECT The subject line of the email that PayPal sends when the transaction is No completed The subject line is the same for all recipients Character length and limitations 255 single byte alphanumeric characters TABLE A 17 MassPay Response Fields The fields in the response are the standard response header fields See successResponse Header Name Value Pair API Developer Guide and Reference April 2007 61 ire NVP API Method and Field Reference Mass Payment 62 April 2007 Name Value Pair API Developer Guide and Reference Error Message Reference This chapter contains error messages for the API Error Response Format Ifthe ACK value is Error or Warning specific API response fields are not returned An error response has the following general format TABLE B 1 Format of an Error Response Response ACK Error amp TIMESTAMP date timeOfRespons Multiple errors can be Fields on Error amp CORRELATIONID debuggingToken amp VERSION 2 300000 returned Each set of amp BUILD buildNumber amp Ll ERRORCODEO errorCode errors has a different L_SHORTMESSAGEO shortMessage numeric suffix starting with 0 and incremented by one for each error amp L_LONGMESSAGEO longMessage amp L_SEVERITYCODE0 severityCode Valida
96. makes it easy to add PayPal to your web application You construct an NVP string and post it to the PayPal server using HTTPS PayPal posts back a reponse in NVP format Integrating with the PayPal API You can develop with the PayPal NVP API using two different approaches Integrate Directly You can integrate directly with the PayPal NVP API using the programming language of your choice This is the most straightforward and flexible approach You can download web samples that show how to integrate directly using PHP Classic ASP and ColdFusion For more information see Appendix C NVP API Web Samples Integrate Using an SDK You can integrate with the NVP API using a software development kit SDK SDKs are provided for Java and ASP NET The SDKs provide simple functions for integrating with the NVP APL Name Value Pair API Developer Guide and Reference April 2007 el Overview Basic Steps For details about the PayPal NVP SDK see Appendix D The Java SDK or Appendix E The ASP NET SDK Samples To help you get started with the PayPal NVP APL samples are provided at https www paypal com IntegrationCenter ic_nvp html Using the samples you can send API calls to the PayPal Sandbox test environment Basic Steps This section describes the basic steps for programming with the PayPal NVP API During application development your application communicates with the PayPal Sandbox test environment The following
97. mitations 19 single byte characters maximum INVNUM Search by invoice identification key as set by you for the original No transaction This field 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 ACCT Search by credit card number as set by you for the original transaction No This field 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 SALUTATION Buyer s salutation No Character length and limitations 20 single byte characters FIRSTNAMI Buyer s first name No GI Character length and limitations 25 single byte characters Name Value Pair API Developer Guide and Reference April 2007 51 a NVP API Method and Field Reference TransactionSearch TABLE A 12 TransactionSearch Request Parameters Continued Parameter Description Required MIDDLENAME Buyer s middle name No Character length and limitations 25 single byte characters LASTNAME Buyer s last name No Character length and limitations 2025 single byte characters SUFFIX Payer s suffix No Character length and limitations 12 single byte characters AUCTIONITEMNU
98. n 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 10002 Restricted Account is restricted Your PayPal merchant account account has been restricted Contact your PayPal account manager for resolution Name Value Pair API Developer Guide and Reference March 2007 67 Error Message Reference Express Checkout API Errors TABLE B 2 General API Errors Error Code 10002 10002 10002 10002 Short Message Authentication Authorization Failed Authentication Authorization Failed Authentication Authorization Failed Restricted account Long Message Correcting This Error Token is not valid API access is disabled for this account Client certificate is disabled Account is restricted Express Checkout API Errors TABLE B 3 SetExpressCheckout API Errors Error Code 10001 10001 10004 10004 Short Message ButtonSource value truncated Internal Error Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Long Message Correcting This Error The transaction could not be loaded Internal Error Transaction refused because of an invalid argument See
99. n the merchant site to No redirect to after a successful giropay payment GIROPAYCANCELURL giropayCancelURL The URL on the merchant site to No redirect to after a giropay or bank transfer payment is cancelled or fails BANKTXNPENDINGURL BanktxnPendingURL The URL on the merchant site to No transfer to after a bank transfer payment Redirecting the Customer to PayPal After selecting a funding source on PayPal the customer is redirected back to your website as in the regular Express Checkout flow There is one additional field REDIRECTREQUIRED returned in the response from both GetExpressCheckoutDetails and DoExpressCheckoutPayment If the value of this field is true you redirect the customer from your Order Review page to https www paypal com webscr cmd complete express checkout amp token TOKEN Append the token that you received in SetExpressCheckout PayPal then redirects the customer from this redirect page to the necessary page for the selected funding source 20 April 2007 Name Value Pair API Developer Guide and Reference Accepting PayPal in Express Checkout a Controlling the Shipping Address Using SetExpressCheckout Completing the Transaction Corresponding the three fields passed to SetExpressCheckout see Table 2 1 SetExpressCheckout fields for giropay you must add the following three additional pages to your website TABLE 2 2 Additional pages required f
100. ndler to save profile data and returned from ProfileHandler to retrieve profile data Sample Applications The PayPal SDK includes sample applications in the SDK_root samples directory Each subdirectory comes with a README file that explains how to set up the application TABLE D 6 PayPal SDK for Java Sample Code in SDK_root samples Subdirectory Descrption Cert API certificates used by the sample applications JSP JavaScript implementation for Apache Tomcat of the following PayPal APIs e Express Checkout for final sale and for authorization e TransactionSearch e GetTransactionDetails e RefundTransaction SampleApp Native Java application to call TransactionSearch and GetTransactionDetails Name Value Pair API Developer Guide and Reference April 2007 107 el The Java SDK Sample Applications Sample API User with API Signature The samples come with an API signature for use with the samples and the PayPal Sandbox This API signature belongs to the following user TABLE D 7 Details of the Sample API Signature API username sdk three apil sdk com API password QFZCWNSHZM8VBG70 API signature A IzJhZZjhg29XQ02qnhapuwxIDzyAZQ92FRP5dq9BzVesOkzbdUONZmOU IMPORTANT You must protect the API signature values in your implementation Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce a
101. ng Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Long Message ShipToStreet Required parameter missing ShipToStreet2 Required parameter missing ShipToCity Required parameter missing ShipToState Required parameter missing ShipToZip Required parameter missing Country Required parameter missing ReqConfirmShipping Required parameter missing NoShipping Required parameter missing AddrOverride Required parameter missing LocaleCode Required parameter missing PaymentAction Required parameter missing Email Required parameter missing Token Required parameter missing PayerID Required parameter missing ItemAmt Required parameter missing ShippingAmt Required parameter missing HandlingTotal Amt Required parameter missing TaxAmt Required parameter missing IPAddress Required parameter missing ShipToName Required parameter missing L_Amt Required parameter missing Amt Required parameter missing L_TaxAmt Required parameter missing AuthorizationID Required parameter missing CompleteType Required parameter missing CurrencyCode Required parameter missing TransactionID Required parameter missing TransactionEntity Required parameter missing Acct Required parameter missing ExpDate Required parameter missing March 2007 Name Value Pair API De
102. ng as described in Request Format on page 14 The NVP format is described in NVP Format on page 12 3 Post the NVP request to the PayPal Sandbox as described in Posting Using HTTPS on page 16 Interpret the Response PayPal processes your request and posts back a reponse in NVP format Add code to your web application to do the following tasks 1 Receive the HTTP post response and extract the NVP string 2 URL decode the parameter values as described in URL Encoding on page 13 3 Take appropriate action for successful and failed reponses Taking Your Application Live After you have finished coding and testing your application deploy your application to the live PayPal server using your PayPal business account and API credentials for that account Set Up a PayPal Business Account When you are ready to deploy your application to the live PayPal server create a PayPal business account on www paypal com Set Up API Credentials To use the APIs you need a set of credentials to identify yourself to PayPal Create an API signature for your business account For instructions on setting up API credentials for the business account go to https www paypal com IntegrationCenter ic_certificate html Name Value Pair API Developer Guide and Reference April 2007 11 Overview Technical Details IMPORTANT If you are using API signature you must protect the API signature values in your implementation Con
103. ngle merchant developers only a single APIProfile instance is needed PayPal provides two implementation classes suitable for the needs of most SDK developers Certificate APIProfile and SignatureA PIProfile However you are free to write a custom implementation if you need additional functionality the default classes do not offer 106 April 2007 Name Value Pair API Developer Guide and Reference The Java SDK ed Sample Applications TABLE D 5 Interface and Classes for SDK Profiles Continued Interface Class Descriptions EWPProfile interface This interface defines the basic information that PayPal needs to know about a user of PayPal s Encrypted Website Payments EWP service Developers must create an instance of EWPProfile for each account that generates the encrypted button code for single merchant users this will just be a single instance PayPal provides a basic implementation class called DefaultE WPProfile suitable for the needs of most SDK developers However you are free to write a custom implementation if you need functionality the default class does not offer ProfileFactory class This class creates both APIProfile and EWPProfile objects It contains static methods that handle the instantiation and construction of profile objects Profiles class This data class represents all profiles the SDK knows about It contains two collections one for APIProfiles and one for EWPProfiles This class is provided to ProfileHa
104. nnot be transaction processed at this time Please try cannot be again later processed at this time Please try again later 10446 Unconfirmed A confirmed email is required to email make this API call 10474 Invalid Data This transaction cannot be The buyer selects the country of residence when processed The country code in they sign up for their PayPal account The country the shipping address must match of residence is displayed after the dash in the title the buyer s country of residence on the Account Overview page 10537 Risk Control The transaction was refused Country Filter because the country was Failure prohibited as a result of your Country Monitor Risk Control Settings 10538 Risk Control The transaction was refused Max Amount because the maximum amount Failure was excceeded as a result of your Maximum Amount Risk Control Settings March 2007 Name Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B 5 DoExpressCheckoutPayment API Errors Error Code 10539 10725 10727 10728 10729 10730 10731 10736 Short Message Payment declined by your Risk Controls settings PayPal Risk Model Shipping Address Country Error Shipping Address I Empty Shipping Address City Empty Shipping Address State Empty Shipping Address Postal Code Empty Shipping Address Country Empty Shipping Address Invalid City Stat
105. o a k ua GE Kle E A dere e eda MG as 113 Complete SDK and API Class Documentation 22 ar rv rv ee 113 Profl esz gan a am aa a a A a do 113 Overview to Profile related Classes 0 o e o 114 Sample Applications naa 115 Sample API User with API Signature 0 kr kr ran 115 Sample API User with API Certificate vr vr rv 116 Installing the Samples in IIS 0 ee 116 Running the Samples knr 116 Appendix F Country Codes 147 Index 123 6 April 2007 Name Value Pair API Developer Guide and Reference Preface This Document The PayPal Name Value Pair API Developer Guide and Reference describes the PayPal Name Value Pair API Intended Audience The PayPal Name Value Pair API Developer Guide and Reference is written for web developers who are implementing solutions using the Name Value Pair API Documentation Problems If you discover any errors in or have any problems with this documentation please email us by following the instructions below Describe the error or problem as completely as possible and give us the document title the date of the document and the page number or page range To contact Developer Technical Support about documentation problems Log in to your account at https developer paypal com by entering your email address and password in th
106. omer These parameters should be ordered sequentially beginning with 0 for example L EMAILO L EMAILI and so forth L NAMEn Display name of the payer These parameters should be ordered sequentially beginning with 0 for example L NAMEO L NAMEL and so forth L TRANSACTIONIDn Seller s transaction ID These parameters should be ordered sequentially beginning with 0 for example L TRANSACTIONIDO L TRANSACTIONIDL and so forth L STATUSn The status of the transaction These parameters should be ordered sequentially beginning with 0 for example L STATUSO L STATUS1 and so forth Name Value Pair API Developer Guide and Reference April 2007 53 EN NVP API Method and Field Reference GetTransactionDetails TABLE A 13 TransactionSearch Response Fields Continued Field Description L AMTn The total gross amount charged including any profile shipping cost and taxes These parameters should be ordered sequentially beginning with 0 for example L AMTO L AMT1 and so forth L FEEAMInN The fee that PayPal charged for the transaction These parameters should be ordered sequentially beginning with 0 for example L FEEAMTO L FEEAMTI1 and so forth L NETAMTn The net amount of the transaction These parameters should be ordered sequentially beginning with 0 for example L NETAMTO L NETAMTI1 and so forth GetTransactionDetails TABLE A 14
107. or giropay integration Page Description Order Completion The page to redirect the customer to after a successful giropay payment Order Cancellation The page to redirect the customer to after a giropay or bank transfer payment is cancelled or fails Order Pending The page to redirect the customer to after a bank transfer payment Controlling the Shipping Address Using SetExpressCheckout You can make changes to the behavior of the shipping address with the REQCONFIRMSHI PPING NOSHIPPING and ADDROVERRIDE parameters in SetExpressCheckout request Note The shipping address is specified in the SHIPTOxxx parameters Suppressing Display of Shipping Address on PayPal To suppress the display of the customer s shipping address on the PayPal web pages set NOSHIPPING to 1 in SetExpressCheckout request You might want to do this if you are selling a product or service that does not require shipping EXAMPLE 2 1 Suppressing the Shipping Address requiredSecurityParameters METHOD SetExpressCheckoutsAMT 10 008 RETURNURL https ww anycompany com orderprocessing orderreview htmlg CANCELURL https ww anycompany com orderprocessing shippinginfo html Request amp NOSHIPPING 1 Response successResponseFields sTOKEN EC 17C76533PL706494P Name Value Pair API Developer Guide and Reference April 2007 21 A Accepting PayPal in E
108. orrecting 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 most payment method likely cause is that the customer s credit card failed bank authorization Another possible though rare cause Is that the final OrderTotal is significantly higher than the original estimated OrderTotal you sent with SetExpressCheckout at Integration Point 1 and the final OrderTotal does not pass PayPal s risk model analysis If the customer has no other PayPal funding source that is likely to succeed DoExpressCheckoutPayment response 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 is missing 10420 Transaction Express Checkout refused PaymentAction is missing because of an invalid argument See additional error messages for details Name Value Pair API Developer Guide and Reference March 2007 79 Error Message Reference Express Checkout API Errors TABLE B 5 DoExpr
109. pay item l The amount is less than or equal to zero Name Value Pair API Developer Guide and Reference March 2007 91 92 Error Message Reference MassPay API Errors TABLE B 8 MassPay API Errors Error Code 10004 10004 10004 10007 10301 10303 10304 10305 10306 10307 Short Message Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Permission denied User not allowed Restricted account Unconfirmed email Limit Exceeded Limit Exceeded Receive only account Long Message The unique id string length exceeds the maximum limit of 30 characters 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 March 2007 Name Value Pair API Develope
110. pplication can access it The sample code does not store these values securely The sample code should never be used in production Sample API User with API Certificate The samples come with an API digital certificate for use with the SDK and the PayPal Sandbox This certificate belongs to the following user TABLE D 8 Details of the SDK Sample API Certificate Location of Certificate SDK_root samples Certs sdk seller p12 API Username sdk seller apil sdk com API Password 12345678 PKCS12 Passphrase password IMPORTANT You must protect the API Certificate values in your implementation 108 Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user executing your ecommerce application can access it The sample code does not store these values securely The sample code should never be used in production April 2007 Name Value Pair API Developer Guide and Reference The ASP NET SDK This section describes how to use the ASP NET SDK for the NVP API and includes the following topics e Installing the ASP NET SDK on page 109 e Profiles on page 113 e Sample Applications on page 115 Installing the ASP NET SDK This section details the software and hardware supported and required by the PayPal SDK installation and post installation tasks Supported Standards The PayPal SDK has been verified to work wit
111. r Guide and Reference Error Message Reference MassPay API Errors TABLE B 8 MassPay API Errors Error Code 10308 10309 10310 10311 10312 10313 10314 10317 10320 10321 10327 Short Message Masspay server configuration error 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 There is some configuration error 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 masspay server is incorrect Please make sure that you are using a correctly formatted input The masspay input file includes invalid Email Internal Error The account does not have sufficient funds to do this masspay The masspay input file includes invalid UserID Name Value Pair API Developer Guide and Reference March 2007 93 Error Message Reference MassPay API Errors 94 March 2007 Name Value Pair API Developer Guide and Reference NVP API Web Samples This chapter describes the NVP API Web Samples which access the NVP API directly This section includes the following topics e Descriptions of the Samples on page 95 e
112. ress of payer Character length and limitations 127 single byte characters PAYERID Unique customer ID Character length and limitations 13 single byte alphanumeric characters PAYERSTATUS Status of payer s email address Verified Unverified FIRSTNAME Payer s first name Character length and limitations 25 single byte characters LASTNAME Payer s last name Character length and limitations 25 single byte characters MIDDLENAME Payer s middle name Character length and limitations 25 single byte characters PAYERBUSINESS Payer s business name Character length and limitations 127 single byte characters SHIPTOCOUNTRYCODE Payment sender s country of residence using standard two character ISO 3166 country codes Character length and limitations Two single byte characters For the list of country codes see Appendix F Country Codes SALUTATION Payer s salutation Character length and limitations 20 single byte characters SUFFIX Payer s suffix Character length and limitations 12 single byte characters ADDRESSOWNER eBay company that maintains this address ADDRESSSTATUS Status of the address on file with PayPal None Confirmed Unconfirmed SHIPTOCITY Name of city Character length and limitations 120 single byte alphanumeric characters SHIPTONAME Person s name associated with this address Character length and limitations 32 single byte alphanumeric c
113. rtial amount with a full refund A transaction id is required 84 March 2007 Name Value Pair API Developer Guide and Reference Error Message Reference RefundTransaction API Errors TABLE B 6 RefundTransaction API Errors Error Code 10004 10004 10004 10004 10004 10007 Short Message Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details Transaction refused because of an invalid argument See additional error messages for details 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 is required Transaction class is not supported The transaction id is not valid You do not have permission to refund this transaction Name Value Pair API Developer Guide and Reference March 2007 85 86 Error Message Reference RefundTransaction API Errors TABLE B 6 RefundTransaction API Errors Short Error Code Message Long Message 10007 Permission You do not have permissions to make this API deni
114. s Allowable Values e Authorization e Order e Sale Default The transaction resulting from DoExpressCheckout Payment request will be a final sale Email address of the buyer as entered during checkout PayPal uses this value to pre fill the PayPal membership sign up portion of the PayPal login page Character length and limit 127 single byte alphanumeric characters Description of items the customer is purchasing Character length and limitations 127 single byte alphanumeric characters Required No recommended No recommended Yes Name Value Pair API Developer Guide and Reference April 2007 37 el NVP API Method and Field Reference Express Checkout TABLE A 2 SetExpressCheckout Request Parameters Continued Parameter Description Required CUSTOM A free form field for your own use such as a tracking number or No other value you want PayPal to return on GetExpressCheckoutDetails response and DoExpressCheckoutPayment response Character length and limitations 256 single byte alphanumeric characters INVNUM Your own unique invoice or tracking number PayPal returns this No value to you on DoExpressCheckoutPayment response Character length and limitations 127 single byte alphanumeric characters REQCONFIRMSHIPPING The value 1 indicates that you require that the customer s shipping No address on file with PayPal be a confirmed address NoTE Setting this field overrides the s
115. s about a mix of secure and insecure graphics GetExpressCheckoutDetails Request TABLE A 5 GetExpressCheckoutDetails Parameters Parameter Description Required METHOD Name of the API GetExpressCheckoutDetails Yes TOKEN A timestamped token the value of which was returned by Yes SetExpressCheckout response Character length and limitations 20 single byte characters Allowable values An unexpired token Name Value Pair API Developer Guide and Reference April 2007 41 el NVP API Method and Field Reference Express Checkout GetExpressCheckoutDetails Response TABLE A 6 GetExpressCheckoutDetails Response Fields Field Description TOKEN The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request Character length and limitations 20 single byte characters Possible values See the description of TOKEN in Table A 4 SetExpressCheckout Response Fields EMAIL Email address of payer Character length and limitations 127 single byte characters PAYERID Unique PayPal customer account identification number Character length and limitations 13 single byte alphanumeric characters PAYERSTATUS Status of payer Character length and limitations 10 single byte alphabetic characters Possible values verified unverified SALUTATION Payer s salutation Character length and limitations 20 single byte characters FIRSTNAME Pay
116. s are detailed in Appendix A NVP API Method and Field Reference Examples of use are in Chapter 2 Accepting PayPal in Express Checkout and Chapter 3 Back Office Administration Response Format A response from the PayPal servers is a URL encoded name value pair string just like the request except it has the following general format TABLE 1 5 General Format of a Successful Response Success ACK Success amp TIMESTAMP date timeOfRespons The examples show the Response amp CORRELAT IONID debuggingToken amp VERSION 2 300000 successful response header fields Fields amp BUILD buildNumber like this successResponseFields API Response amp NAME1 valuel amp NAME2 value2 amp NAME3 value3 amp Fields Each response includes the ACK field If the ACK field s value is Success or Success With Warning you should process the API response fields In a successful response you can ignore all fields up to and including the BUILD field The important fields begin after the BUILD field The possible successful response fields for each method are detailed in Appendix A NVP API Method and Field Reference What you do with the fields depends on the particular API method you are calling such as filling in a FORM for your user updating your database and so on Name Value Pair API Developer Guide and Reference April 2007 15 Overview Technical Details Error Responses If the ACK value is
117. s immediately after the top level lt configuration gt tag lt configuration gt lt configSections gt lt section name paypal type com paypal sdk core ConfigSectionHandler paypal base gt lt configSections gt The optional custom settings themselves are in a lt paypal gt block later in the file lt paypal gt custom settings lt paypal gt SDK Logging The PayPal SDK uses log4net public domain logging software For information about log4net see the log4net documentation at http logging apache org log4net release manual introduction html This section describes SDK logging levels in which configuration files you set the desired level and request logging Name Value Pair API Developer Guide and Reference April 2007 111 S The ASP NET SDK Installing the ASP NET SDK Log Levels The SDK varies the amount of detail it records according to four logging levels TABLE E 4 SDK Logging Levels Level Description ALL Same as DEBUG ERROR Log only severe errors INFO Date time of API operation operation name elapsed time success or failure indication DEBUG Full text of requests and responses and other debugging messages DEBUG logging can degrade the performance of the SDK Be careful about using it for day to day operation NOTE Because requests and responses are asynchronous the recording of requests and responses might appear out of sequence in the log file Setting
118. s not exceed 10 000 USD in any currency No currency symbol Regardless of currency decimal separator is a period and the optional thousands separator is a comma Equivalent to nine characters maximum for USD Possible Values Transaction specific CURRENCYCODE A three character currency code for one of the currencies listed in PayPay Supported Transactional Currencies Default USD FEEAMT PayPal fee amount charged for the transaction Character length and limitations Does not exceed 10 000 USD in any currency No currency symbol Regardless of currency decimal separator is a period and the optional thousands separator is a comma Equivalent to nine characters maximum for USD Possible values Transaction specific SETTLEAMT Amount deposited in your PayPal account after a currency conversion Possible values Transaction specific TAXAMT Tax charged on the transaction Character length and limitations Does not exceed 10 000 USD in any currency No currency symbol Regardless of currency decimal separator is a period and the optional thousands separator is a comma Equivalent to nine characters maximum for USD Possible values Transaction specific EXCHANGERATE Exchange rate if a currency conversion occurred Relevant only if your are billing in their non primary currency If the customer chooses to pay with a currency other than the non primary currenc
119. section Taking Your Application Live on page 11 describes how to move your application to the live PayPal environment NoTE The simplest way to get started is to download and try out the sample applications as described in Integrating with the PayPal API on page 9 Create a Web Application Your NVP API implementation usually runs in a web application You can write your own application or use one of the samples as a starting point Get API Credentials To access the PayPal API you need API credentials either an API signature or API certificate that identify you Use the following sample API signature and password in your sample programs that run in the PayPal Sandbox test environment Note If you are using the samples this signature is already in the code TABLE 1 1 Details of the Sample API Signature API username sdk three apil sdk com API password QFZCWNSHZM8VBG70 API signature A IzJhZZjhg29xXQ02qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONZmOU 10 April 2007 Name Value Pair API Developer Guide and Reference Overview mm Taking Your Application Live Create and Post the Request Create an NVP request string and post it to PayPal sandbox server Add code to your web application to do the following tasks 1 URL encode the name and value parameters in the request to ensure correct transmission of all characters This is described in URL Encoding on page 13 2 Construct the NVP API request stri
120. sider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user that executes your ecommerce application can access it The sample code does not store these values securely The sample code should never be used in production NoTE While API signature is recommended you can also use API certificate Modify Your Code In your application change the following items from the PayPal Sandbox values to the live PayPal server values e The server address in the URL See Posting Using HTTPS on page 16 e API credentials you set up in Set Up API Credentials on page 11 Technical Details This section describes details of the technologies used by the PayPal NVP API Request Response Model When you use the PayPal NVP API you post an NVP request to PayPal and PayPal posts back an NVP response URL Format The request and response are in URL encoded format which is defined by the Worldwide Web Consortium W3C URL is defined as part of the URI specification Find out more about URI at http www w3 org Addressing NVP Format NVP is a way of specifying names and values in a string NVP is the informal name for the query in the URI specification The NVP string is appended to the URL An NVP string conforms to the following guidelines e The name is separated from the value by an equal sign For example FIRSTNAME Robert
121. ss Checkout TABLE A 2 SetExpressCheckout Request Parameters Continued Parameter GIROPAYCANCELURL BANKTXNPENDINGURL CURRENCYCODE MAXAMT PAYMENTACTION EMAIL Description URL of your website where the user gets redirected when a giropay or electronic funds transfer transaction fails URL of your website where the user gets redirected when he has initiated an electronic funds transfer The total cost of the order to the customer If shipping cost and tax charges are known include them in this value if not this value should be the current sub total of the order NOTE Limitations Must not exceed 10 000 USD in any currency No currency symbol Must have two decimal places decimal separator must be a period and the optional thousands separator must be a comma A three character currency code for one of the currencies listed in PayPal Supported Transactional Currencies Default USD The expected maximum total amount of the complete order including shipping cost and tax charges NoTE Limitations Must not exceed 10 000 USD in any currency No currency symbol Must have two decimal places decimal separator must be a period and the optional thousands separator must be a comma How you want to obtain payment e Sale indicates that this is a final sale for which you are requesting payment Character length and limit Up to 13 single byte alphabetic character
122. ssage 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 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 DoExpressCheckout Payment 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 DoExpressCheckout Payment API calls for any single token value after which the token becomes invalid March 2007 Name Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors TABLE B 5 DoExpressCheckoutPayment API Errors Error Short Code Message Long Message C
123. strator IIS running and WinHttpCertCfg exe is in your PATH To install the samples in Microsoft IIS 1 Run SDK_root samples ASPNET InstallSample bat 2 To enable logging change the permissions on the localComputerName VASPNET folder to Full Control InstallSample bat does the following Creates a virtual directory named PaypalASPNETSample in IIS that points to SDK_root samples ASPNET Loads the sample API certificate SDK_root samples Certs sdk seller p12 into the Microsoft Windows system store Uses the WinHttpCertCfg exe command to grant unlimited access for account Everyone to that certificate Running the Samples To run the samples in Internet Explorer open http localhost PaypalASPNETSamples 116 April 2007 Name Value Pair API Developer Guide and Reference NoTE This table lists country codes defined by ISO 3166 1 Table 1 Country Codes Country Codes Country AFGHANISTAN LAND ISLANDS ALBANIA ALGERIA AMERICAN SAMOA ANGUILLA ANTARCTICA ANTIGUA AND BARBUDA ARGENTINA ARMENIA ARUBA AUSTRALIA AUSTRIA AZERBAIJAN BAHAMAS BAHRAIN BANGLADESH BARBADOS Code DZ AS AD AO AI AQ AG AW AU AT BS BH BD BB Country BELARUS BELGIUM BELIZE BENIN BERMUDA BHUTAN BOLIVIA BOSNIA AND HERZEGOVINA BOTSWANA BOUVET ISLAND BRAZIL BRITISH INDIAN OCEAN TERRITORY BRUNEI DARUSSALAM BULGARIA BURKINA FASO BURUNDI CAMBODIA CAM
124. te Payment has already been made for this PayPal checks that invoice InvoicelD InvoicelD values are unique for any particular merchant If you send an InvoicelD value already associated with another transaction in the PayPal system PayPal returns error code 10412 You might not be able to correct this error during an actual checkout If you get this error research why might occur and modify your implementation of Express Checkout to ensure that you generate unique invoice identification numbers 10415 Transaction A successful transaction has already been PayPal allows a token only refused completed for this token once for a successful because of an transaction invalid Handling this error argument See If you determine that your additionalerror customers are clicking your ein adi for Place Order button twice details PayPal recommends that you disable the button after your customer has clicked it 10425 Express Express Checkout has been disabled for this Checkout has merchant Please contact Customer Service been disabled for this merchant 10432 Transaction Invoice ID value exceeds maximum allowable refused length because of an invalid argument See additional error messages for details Name Value Pair API Developer Guide and Reference March 2007 71 Error Message Reference Express Checkout API Errors TABLE B 3 SetExpressCheckout API Errors Error Code 10433 10434 10436 10437 1043
125. tegrationshandbuch Express Kaufabwicklung for details on Express Checkout including page flow integration points button placement and page design Express Checkout with PayPal requires the following steps 1 Starting the Checkout Using SetExpressCheckout 2 Redirecting the Customer s Browser to PayPal Login Page 3 Getting Payer Details Using GetExpressCheckoutDetails 4 Making a Sale Using DoExpressCheckoutPayment In SetExpressCheckout response you obtain a TOKEN that uniquely identifies this three step transaction You pass this TOKEN in the request to GetExpressCheckoutDetails and DoExpressCheckoutPayment Both GetExpressCheckoutDetails and DoExpressCheckoutPayment return this TOKEN in the response This example shows basic checkout using the minimum number of parameters Name Value Pair API Developer Guide and Reference April 2007 17 Fe Accepting PayPal in Express Checkout Basic Checkout with PayPal 1 Starting the Checkout Using SetExpressCheckout The SetExpressCheckout request method notifies PayPal that you are using Express Checkout to obtain payment from your customer You must always include the following parameters in SetExpressCheckout request e AMT e RETURNURL e CANCELURL You are also advised to include the following parameters to ensure a smooth flow in case the funding methods giropay or electronic funds transfer are being used e GIROPAYSUCCESSURL e GIROPAYFAILURL
126. the buyer returns from PayPal and has authorized the payment Displays the payer details returned by the GetExpressCheckoutDetails response and calls DoExpressCheckoutPayment ext to complete the payment authorization Called by ReviewOrder ext Calls DoExpressCheckoutPayment ext and CallerService ext 96 April 2007 Name Value Pair API Developer Guide and Reference NVP API Web Samples Descriptions of the Samples al TABLE C 1 Express Checkout Files Continued File Description DoExpressCheckoutPayment ext This functionality is called to complete the payment with PayPal and display the result to the buyer The code constructs and sends the DoExpressCheckout Payment request string to the PayPal server Called by GetExpressCheckoutDetails ext and CallerService ext Getting Transaction Details This sample shows how to use the GetTransactionDetails request Access this sample from the following choice displayed on index html or Default htm GetTransactionDetails Gets transaction details for a specific transaction ID The main page displays a text box where the user enters a transaction ID When the user clicks the Submit button the code constructs an NVP API request to GetTransactionDetails and sends it to the PayPal server The primary files for this sample are TABLE C 2 Get Transaction Details Files File Description GetTransactionDetails ext This is the main page for GetTransactionDetails sampl
127. tion Errors TABLE B 1 Validation Errors Error Code Short Message Long Message 81000 Missing Parameter Required Parameter Missing Unable to identify parameter 81001 Invalid Parameter A Parameter is Invalid Unable to identify parameter 81002 Unspecified Method Method Specified is not Supported 81003 Unspecified Method No Method Specified 81004 Unspecified Method No Request Received 81100 Missing Parameter OrderTotal Amt Required parameter missing 81101 Missing Parameter MaxAmt Required parameter missing 81102 Missing Parameter RetumURL Required parameter missing 81103 Missing Parameter NotifyURL Required parameter missing 81104 Missing Parameter CancelURL Required parameter missing Name Value Pair API Developer Guide and Reference March 2007 63 64 Error Message Reference Validation Errors TABLE B 1 Validation Errors Error Code 81105 81106 81107 81108 81109 81110 81111 81112 81113 81114 81115 81116 81117 81118 81119 81120 81121 81122 81123 81124 81125 81126 81127 81128 81129 81130 81131 81132 81133 81134 Short Message Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missi
128. tionDetails Response Fields Continued Parameter Description PENDINGREASON NOTE PendingReason is returned in the response only if PaymentStatus is Pending The reason the payment is pending e none No pending reason e 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 e echeck The payment is pending because it was made by an eCheck that has not yet cleared e 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 e 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 e verify The payment is pending because you are not yet verified You must verify your account before you can accept this payment e other The payment is pending for a reason other than those listed above For more information contact PayPal Customer Service The reason for a reversal if TransactionType is reversal e none No reason code e chargeback A reversal has occurred on this transaction due to a chargeback by your custom
129. tribution 2 Unzip the zipfile to any directory of you choose Note We refer to the directory in which you choose to extract the SDK as SDK root Post installation Set up This section details steps you must take before you start using the PayPal SDK Adding SDK JAR Files to CLASSPATH Before developing applications with the Java SDK be sure to add the SDK JAR files in SDK_root 1ib to your CLASSPATH environment variable SDK Directories and Optional Configurations The Java SDK components are organized into different subdirectories as shown in Table D 3 PayPal SDK for Java Directories and Contents TABLE D 3 PayPal SDK for Java Directories and Contents Directory Descrption cert PayPal public certificates for Live PayPal and PayPal Sandbox docs SDK API documentation lib SDK libraries licenses License files 104 April 2007 Name Value Pair API Developer Guide and Reference The Java SDK El Complete SDK and API Class Documentation TABLE D 3 PayPal SDK for Java Directories and Contents Continued Directory Descrption samples Example code that use the SDK src SDK source code tools Third party applications Complete SDK and API Class Documentation Complete Javadoc documentation for all PayPal SDK interfaces classes methods structures and data types are included with the SDK distribution To view the documentation open the following file with your web browser SDK_root docs index html
130. uired 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 TABLE B 4 GetExpressCheckoutDetails API Errors Error Short Code Message 10001 Internal Error 10001 Internal Error error Long Message Correcting This Error Internal Error Transaction failed due to internal March 2007 Name Value Pair API Developer Guide and Reference Error Message Reference Express Checkout API Errors mm TABLE B 4 GetExpressCheckoutDetails API Errors Error Short Code Message Long Message Correcting This Error 10001 ButtonSource The transaction could not be value loaded truncated 10001 ButtonSource The transaction could not be value loaded truncated 10004 Transaction Transaction refused because of refused an invalid argument See because ofan additional error messages for invalid details argument See additional error messages for details 10004 Transaction The transaction id is not valid refused because of an invalid argument See additional error messages for details 10004 Invalid You can not get the details for transaction this type of transaction type 10004 Transaction The transaction could not be refused loaded because of an invalid argument See additional error messages for details 10004 Transaction The transact
131. veloper Guide and Reference Error Message Reference Validation Errors TABLE B 1 Validation Errors Error Code 81135 81136 81137 81138 81139 81140 81141 81142 81143 81144 81145 81146 81147 81148 81149 81150 81200 81201 81203 81205 81206 81207 81208 81209 81210 81211 81212 81213 81214 81215 Short Message Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Missing Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Invalid Parameter Long Message FirstName Required parameter missing LastName Required parameter missing Street Required parameter missing Street2 Required parameter missing City Required parameter missing State Required parameter missing Zip Required parameter missing CountryCode Required parameter missing RefundType Required parameter missing StartDate Required parameter missing EndDate Required parameter missing MPID Required parameter missing CreditCardType Required parameter missing User Required parameter missing Pwd Required
132. xpress Checkout Controlling the Shipping Address Using SetExpressCheckout GetExpressCheckoutDetails does not return the shipping address EXAMPLE 2 2 GetExpressCheckoutDetails frequiredSecurityParametersjsMETHOD GetExpressCheckoutDetails amp Request TOKEN EC 17C76533PL706494P successResponseFields s TOKEN EC 17C76533PL706494P amp EMATL abcdef anycompany com amp PAYERID 95HR9CM6D5602 amp PAYERSTATUS veri fied amp FIRSTNAME John amp LASTNAME Smith amp COUNTRYCODE US amp Response ADDRESSID PayPal amp ADDRESSSTATUS None Overriding the Shipping Address Stored on PayPal To override the shipping address stored on PayPal call SetExpressCheckout to set ADDROVERRIDE to 1 and set the shipping address fields see Table A 3 Ship to Address Optional The customer cannot edit the address if it has been overridden EXAMPLE 2 3 Overriding the Shipping Address requiredSecurityParameters METHOD SetExpressCheckoutsAMT 10 008 RETURNURL https ww anycompany com orderprocessing orderreview htmlg CANCELURL https ww anycompany com orderprocessing shippinginfo html amp SHIPTONAME Peter Smi thsSHIPTOSTREET 1 444 Main St SHIPTOCITY SAN JOSE amp SHIPTOSTATE CA amp SHIPTOCOUNTRYCODE US amp SHI PTOZIP 99911 Request ADDROVERRIDE 1 Response successResponseFields sTOKEN EC 17C76533PL706494P
133. y the conversion occurs in the customer s account Character length and limitations a decimal that does not exceed 17 characters including decimal point Possible values Transaction specific 48 April 2007 Name Value Pair API Developer Guide and Reference NVP API Method and Field Reference Express Checkout Ia TABLE A 9 DoExpressCheckout Payment Response Fields Continued Field Description PAYMENTSTATUS Status of the payment Completed The payment has been completed and the funds have been added successfully to your account balance Pending The payment is pending See the PendingReason element for more information Fu ENDINGREASON The reason the payment is pending e none No pending reason e 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 e echeck The payment is pending because it was made by an eCheck that has not yet cleared e 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 e multi currency You do not have a balance in the currency sent and you do not have your Payment Receiving Preferences set to automatically conv
134. y to the customer the same amount that the merchant sends to PayPal in the AMT parameter with the DOExpressCheckout Payment request API Name Value Pair API Developer Guide and Reference April 2007 43 el NVP API Method and Field Reference Express Checkout TABLE A 7 DoExpressCheckoutPayment Parameters Parameter METHOD TOKEN PAYMENTACTION PAYERID DESC CUSTOM INVNUM GI BUTTONSOURC Description Name of the API DoExpressCheckoutPayment The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request Character length and limitations 20 single byte characters How you want to obtain payment e Sale indicates that this is a final sale for which you are requesting payment Character length and limit Up to 13 single byte alphabetic characters Allowable Values e Authorization e Order e Sale Default The transaction resulting from DoExpressCheckoutPayment request will be a final sale Unique PayPal customer account identification number as returned by GetExpressCheckoutDetails response Character length and limitations 13 single byte alphanumeric characters Total of order including shipping handling and tax NoTE Limitations Must not exceed 10 000 USD in any currency No currency symbol Must have two decimal places decimal separator must be a period and the optional thousands
135. yment API Errors Error Message Reference Express Checkout API Errors Error Code 10004 10004 10007 10406 10408 10409 10410 10411 10412 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 Permission denied Transaction refused because of an invalid argument See additional error messages for details Express Checkout token is missing You re not authorized to access this info Invalid token This Express Checkout session has expired Duplicate invoice Long Message 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 This Express Checkout session has expired Token value is no longer valid Payment has already been made for this InvoicelD Correcting This Error Name Value Pair API Developer Guide and Reference March 2007 77 78 Error Message Reference Express Checkout API Errors TABLE B 5 DoExpressCheckoutPayment API Errors Error Code 10413 10414 10415 10416 Short Me

PayPal Name-Value Pair API - 2007 Reference Manual

Contents

Download Pdf Manuals

Related Search

Related Contents