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.
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.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Documentation Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Chapter 1 Overview . . . . . . .
Contents Completing the Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Controlling the Shipping Address Using SetExpressCheckout . . . . . . . . . . . . . . . 21 Suppressing Display of Shipping Address on PayPal . . . . . . . . . . . . . . . . . . 21 Overriding the Shipping Address Stored on PayPal . . . . . . . . . . . . . . . . . . . 22 Changing the Language on the PayPal Login Page Using SetExpressCheckout . . . . . .
Contents RefundTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 TransactionSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 GetTransactionDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Mass Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Appendix B Error Message Reference . . . . . . . . . . . . . . . . . . 63 Error Response Format . . . . . . . . .
Contents Appendix D The Java SDK . . . . . . . . . . . . . . . . . . . . . . . 103 Installing the Java SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 Supported Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103 Recommended Hardware Configuration. . . . . . . . . . . . . . . . . . . . . . . . .104 Download and Unzip the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104 Post-installation Set-up . . . . . . . . . . . . . . . . . . .
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.
Preface Revision History Revision History Revision history for PayPal Name-Value Pair API Developer Guide and Reference. TABLE P.1 Revision History Date Description April 2007 Revised document to represent specifics for Germany. February 2007 8 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.
1 Overview This chapter describes the PayPal Name-Value Pair (NVP) API at a high level and contains the following sections: z Introducing the PayPal NVP API z Basic Steps z Taking Your Application Live z Technical Details Introducing the PayPal NVP API The PayPal NVP API is a simple programmatic interface that allows you, the merchant, to access PayPal’s business functionality to: z Accept PayPal in checkout on your website using Express Checkout.
Overview Basic Steps For details about the PayPal NVP SDK, see Appendix D, “The Java SDK” or Appendix E, “The ASP.NET SDK.” Samples To help you get started with the PayPal NVP API, samples are provided at https://www.paypal.com/IntegrationCenter/ic_nvp.html. Using the samples, you can send API calls to the PayPal Sandbox test environment. Basic Steps This section describes the basic steps for programming with the PayPal NVP API.
Overview 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 string as described in “Request Format” on page 14. The NVP format is described in “NVP Format” on page 12. 3.
Overview Technical Details IMPO RTANT: If you are using API signature, 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 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.
Overview Technical Details URL-Encoding The request and response are URL-encoded. URL-encoding ensures that you can transmit special characters, characters that are not allowed in a URL, and characters that have special meaning in a URL, such as the equal sign and ampersand. For example, the following NVP string: NAME=Robert Moore&COMPANY=R. H.
Overview Technical Details Request Format Each NVP request consists of required and optional parameters and their values. Parameter names are not case sensitive. The examples in this document use UPPERCASE for parameter names and divide the parameters into required security parameters and body parameters. TABLE 1.3 General Format of a Request Required Security Parameters USER=apiUsername&PWD=apiPassword&SIGNATURE=apiSignature &SUBJECT=optionalThirdPartyEmailAddress&VERSION=2.
Overview Technical Details You may see sample code where these values are stored in an HTML form. The following is an example of what you should NOT do in production:
Overview Technical Details Error Responses If the ACK value is Error or Warning, API response fields are not returned. An error response has the following general format. TABLE 1.6 Format of an Error Response Response Fields on Error ACK=Error&TIMESTAMP=date/timeOfResponse& CORRELATIONID=debuggingToken&VERSION=2.300000& BUILD=buildNumber&L_ERRORCODE0=errorCode& L_SHORTMESSAGE0=shortMessage L_LONGMESSAGE0=longMessage &L_SEVERITYCODE0=severityCode Multiple errors can be returned.
2 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.
2 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.
Accepting PayPal in Express Checkout Basic Checkout with PayPal 2 3. Getting Payer Details Using GetExpressCheckoutDetails The GetExpressCheckoutDetails method returns information about the customer, including name and address stored on PayPal. You must always include the following parameters in GetExpressCheckoutDetails: z TOKEN: use the value from SetExpressCheckout response The response contains this TOKEN and customer details. EXAMPLE 2.
2 Accepting PayPal in Express Checkout Support giropay and electronic funds transfer Response [successResponseFields&TOKEN=EC-0E881823PA052770A& TRANSACTIONID=8SC56973LM923823H&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T20:16:05Z&AMT=10.00& CURRENCYCODE=USD&FEEAMT=0.59&TAXAMT=0.
Accepting PayPal in Express Checkout Controlling the Shipping Address Using SetExpressCheckout 2 Completing the Transaction Corresponding the three fields passed to SetExpressCheckout (see Table 2.1, “SetExpressCheckout fields for giropay”), you must add the following three additional pages to your website: TABLE 2.2 Additional pages required for giropay integration Page Description Order Completion The page to redirect the customer to after a successful giropay payment.
2 Accepting PayPal in Express Checkout Controlling the Shipping Address Using SetExpressCheckout GetExpressCheckoutDetails does not return the shipping address. EXAMPLE 2.2 GetExpressCheckoutDetails Request [requiredSecurityParameters]&METHOD=GetExpressCheckoutDetails& TOKEN=EC-17C76533PL706494P [successResponseFields]&TOKEN=ECResponse 17C76533PL706494P&EMAIL=abcdef@anycompany.
Accepting PayPal in Express Checkout Changing the Language on the PayPal Login Page Using SetExpressCheckout 2 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.
2 Accepting PayPal in Express Checkout Form-Filling Your Payment Review Page Using GetExpressCheckoutDetails Specifying Logo and Color Settings Individually You can modify the PayPal web pages to look like your own web pages by setting the following parameters in SetExpressCheckout: z HDRIMG: specify an image to appear at the top left of the payment page z HDRBORDERCOLOR: set the border color around the header of the payment page z z HDRBACKCOLOR: set the background color for the background of the h
Accepting PayPal in Express Checkout Making a Sale Using DoExpressCheckoutPayment 2 Get the payer name from the following parameters in GetExpressCheckoutDetails response: z SALUTATION z FIRSTNAME z MIDDLENAME z LASTNAME z SUFFIX Get the shipping address from the following parameters in GetExpressCheckoutDetails response: z SHIPTONAME z SHIPTOSTREET z SHIPTOSTREET2 z SHIPTOCITY z SHIPTOSTATE z SHIPTOCOUNTRYCODE z SHIPTOPHONENUM z SHIPTOZIP Making a Sale Using DoExpressCheckoutPay
2 Accepting PayPal in Express Checkout Including Line Item Details Using DoExpressCheckoutPayment [successResponseFields]&TOKEN=EC-8AX1275942659774U& TRANSACTIONID=1MA55216691247718&TRANSACTIONTYPE=expresscheckout& PAYMENTTYPE=instant&ORDERTIME=2006-08-22T22:39:13Z&AMT=10.00& CURRENCYCODE=USD&FEEAMT=0.59&TAXAMT=0.
Accepting PayPal in Express Checkout Including Subtotals Using DoExpressCheckoutPayment 2 Here are examples of ITEMAMT and TAXAMT: ITEMAMT = (L_AMT0 * L_QTY0) + (L_AMT1 + L_QTY1) + L_AMT2 TAXAMT = (L_TAXAMT0 * L_QTY0) + (L_TAXAMT1 * L_QTY1) + L_TAXAMT2 N O T E : 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.
2 Accepting PayPal in Express Checkout Updating the Shipping Address Using DoExpressCheckoutPayment z DESC: item description z CUSTOM: field for your own use z INVNUM: your invoice or tracking number These three parameters may have been set in SetExpressCheckout. EXAMPLE 2.12 Updating Order Details [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& TOKEN=EC5JA9268562132991T&PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=10.
Accepting PayPal in Express Checkout Updating the Shipping Address Using DoExpressCheckoutPayment 2 EXAMPLE 2.13 Updating the Shipping Address [requiredSecurityParameters]&METHOD=DoExpressCheckoutPayment& Request METHOD=DoExpressCheckoutPayment&TOKEN=EC-47C20533CU265432F& PAYERID=95HR9CM6D56Q2&PAYMENTACTION=Sale&AMT=10.
2 30 Accepting PayPal in Express Checkout Updating the Shipping Address Using DoExpressCheckoutPayment April 2007 Name-Value Pair API Developer Guide and Reference
3 Back-Office Administration This section gives you examples of the following functions: z “Refunding Using RefundTransaction” on page 31 z “Searching for Transactions Using TransactionSearch” on page 32 z “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 of a transaction. Specify the original transaction ID and the refund type: Full or Partial.
3 Back-Office Administration 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 Request Response [requiredSecurityParameters]&METHOD=RefundTransaction&TRANSACTIONID=01945456967386 7 &REFUNDTYPE=Partial&AMT=12.95&NOTE=Customer+changed+mind. [successResponseFields]&REFUNDTRANSACTIONID=1H0011898K637700R &FEEREFUNDAMT=0.38&GROSSREFUNDAMT=12.
Back-Office Administration Viewing Details of a Single Transaction Using GetTransactionDetails 3 Vi e w i n g D e ta i l s o f a S i n g l e Tr a n s a c t i o n U s i n g G e t Tr a n s a c t i o n D e ta i l s To view all details about a single transaction, use GetTransactionDetails. EXAMPLE 3.
3 34 Back-Office Administration Viewing Details of a Single Transaction Using GetTransactionDetails April 2007 Name-Value Pair API Developer Guide and Reference
A 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.
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.
NVP API Method and Field Reference Express Checkout TABLE A.2 SetExpressCheckout Request Parameters (Continued) Parameter Description Required GIROPAYCANCELURL URL of your website where the user gets redirected when a giropay or electronic funds transfer transaction fails. No (recommended) BANKTXNPENDINGURL URL of your website where the user gets redirected when he has initiated an electronic funds transfer. No (recommended) AMT The total cost of the order to the customer.
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 other value you want PayPal to return on GetExpressCheckoutDetails response and DoExpressCheckoutPayment response. Character length and limitations: 256 single-byte alphanumeric characters No INVNUM Your own unique invoice or tracking number.
NVP API Method and Field Reference Express Checkout TABLE A.2 SetExpressCheckout Request Parameters (Continued) Parameter Description Required LOCALECODE Locale of pages displayed by PayPal during Express Checkout. Character length and limitations: Any two-character country code. The following two-character country codes are supported by PayPal: z AU z DE z FR z IT z GB z ES z US Any other value will default to US. No N O T E : For the list of country codes, see Appendix Codes.
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 Address are described in Table A.3, “Ship to Address (Optional).” No I M P O R T A N T : Ship to Address is optional, but if you include it, certain fields are required. TABLE A.
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. N O T E : The token expires after three hours. If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request.
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.
NVP API Method and Field Reference Express Checkout 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 SHIPTOCOUNTRYCODE Country code. Character limit: Two single-byte characters.
NVP API Method and Field Reference Express Checkout TABLE A.7 DoExpressCheckoutPayment Parameters Parameter Description Required? METHOD Name of the API: DoExpressCheckoutPayment Yes TOKEN The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request.
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 transaction. No N O T E : 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.
NVP API Method and Field Reference Express Checkout TABLE A.7 DoExpressCheckoutPayment Parameters (Continued) Parameter Description Required? L_NUMBERn Item number. Character length and limitations: 127 single-byte characters No These parameters should be ordered sequentially beginning with 0, for example, L_NUMBER0, L_NUMBER1, and so forth. Item quantity.
NVP API Method and Field Reference Express Checkout TABLE A.8 Optional Ship to Address (Continued) Parameter Description Required? SHIPTOSTATE State or province. Character length and limitations: 40 single-byte characters Yes SHIPTOCOUNTRYCODE Country code. Character limit: Two single-byte characters For the list of country codes, see Appendix F, “Country Codes.” Yes SHIPTOZIP U.S. ZIP code or other country-specific postal code.
NVP API Method and Field Reference Express Checkout TABLE A.9 DoExpressCheckout Payment Response Fields (Continued) Field Description PAYMENTTYPE Indicates whether the payment is instant or delayed. Character length and limitations: Seven single-byte characters Possible values: z none z echeck z instant ORDERTIME Time/date stamp of payment Possible values: Transaction specific AMT The final amount charged, including any shipping and taxes from your Merchant Profile.
NVP API Method and Field Reference Express Checkout 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.
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 Character length and limitations: 17 single-byte alphanumeric characters Yes REFUNDTYPE Type of refund you are making z Other z Full z Partial Yes AMT Refund amount. Amount is required if RefundType is Partial.
NVP API Method and Field Reference TransactionSearch 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.
NVP API Method and Field Reference TransactionSearch TABLE A.
NVP API Method and Field Reference TransactionSearch TABLE A.12 TransactionSearch Request Parameters (Continued) Parameter Description Required STATUS Search by transaction status: z Pending: The payment is pending. The specific reason the payment is pending is returned by the GetTransactionDetails API PendingReason field. z Processing: The payment is being processed. z Success: The payment has been completed and the funds have been added successfully to your account balance.
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_AMT0, L_AMT1, and so forth. L_FEEAMTn The fee that PayPal charged for the transaction These parameters should be ordered sequentially beginning with 0, for example, L_FEEAMT0, L_FEEAMT1, and so forth.
NVP API Method and Field Reference GetTransactionDetails TABLE A.15 GetTransactionDetails Response Fields (Continued) Parameter Description EMAIL Email address of payer Character length and limitations: 127 single-byte characters PAYERID Unique customer ID. Character length and limitations: 13 single-byte alphanumeric characters.
NVP API Method and Field Reference GetTransactionDetails TABLE A.15 GetTransactionDetails Response Fields (Continued) 56 Parameter Description SHIPTOSTATE State or province. Character length and limitations: 120 single-byte alphanumeric characters SHIPTOSTREET First street address. Character length and limitations: 300 single-byte alphanumeric characters SHIPTOSTREET2 Second street address.
NVP API Method and Field Reference GetTransactionDetails 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.
NVP API Method and Field Reference GetTransactionDetails TABLE A.15 GetTransactionDetails Response Fields (Continued) Parameter Description PENDINGREASON N O T E : PendingReason is returned in the response only if PaymentStatus is Pending.
NVP API Method and Field Reference GetTransactionDetails 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_name1, item_name2, and so forth.
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.
NVP API Method and Field Reference Mass Payment TABLE A.16 MassPay Parameters (Continued) Require d? Parameter Description L_UNIQUEIDn Transaction-specific identification number for tracking in an accounting system. Character length and limitations: 30 single-byte characters. No whitespace allowed. No These parameters should be ordered sequentially beginning with 0, for example, L_UNIQUEID0, L_UNIQUEID1, and so forth. L_NOTEn Custom note for each recipient.
NVP API Method and Field Reference Mass Payment 62 April 2007 Name-Value Pair API Developer Guide and Reference
B Error Message Reference This chapter contains error messages for the API. Error Response Format If the ACK value is Error or Warning, specific API response fields are not returned. An error response has the following general format TABLE B.1 Response Fields on Error Format of an Error Response ACK=Error&TIMESTAMP=date/timeOfResponse &CORRELATIONID=debuggingToken&VERSION=2.
Error Message Reference Validation Errors TABLE B.
Error Message Reference Validation Errors TABLE B.
Error Message Reference Validation Errors TABLE B.
Error Message Reference General API Errors General API Errors TABLE B.2 General API Errors Error Code Short Message Long Message Correcting This Error This error can be caused by an incorrect API username, an incorrect API password, or an invalid API signature. Make sure that all three of these values are correct. For your security, PayPal does not report exactly which of these three values might be in error.
Error Message Reference Express Checkout API Errors TABLE B.2 General API Errors Error Code Short Message Long Message Correcting This Error 10002 Authentication /Authorization Failed Token is not valid 10002 Authentication /Authorization Failed API access is disabled for this account 10002 Authentication /Authorization Failed Client certificate is disabled 10002 Restricted account Account is restricted Express Checkout API Errors TABLE B.
Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Short Message Long Message 10007 Permission denied You do not have permissions to make this API call 10102 PaymentActio n of Order Temporarily Unavailable PaymentAction of Order is temporarily unavailable. Please try later or use other PaymentAction. 10103 Please use another Solution Type. Your Solution Type is temporarily unavailable. If possible, please use another Solution Type.
Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors 70 Error Code Short Message Long Message 10410 Invalid token Invalid token. 10411 This Express Checkout session has expired. This Express Checkout session has expired. Token value is no longer valid. March 2007 Correcting This Error... The token returned by SetExpressCheckout response expires after three hours.
Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Short Message Long Message Correcting This Error... 10412 Duplicate invoice Payment has already been made for this InvoiceID. PayPal checks that InvoiceID values are unique for any particular merchant. If you send an InvoiceID value already associated with another transaction in the PayPal system, PayPal returns error code 10412. You might not be able to correct this error during an actual checkout.
Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code 72 Short Message Long Message Correcting This Error... 10433 Transaction refused because of an invalid argument. See additional error messages for details. Value of OrderDescription element has been truncated. 10434 Transaction refused because of an invalid argument. See additional error messages for details. Value of Custom element has been truncated.
Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code Short Message Long Message 10439 Transaction refused because of an invalid argument. See additional error messages for details. cpp-header-image value exceeds maximum allowable length. 10440 Transaction refused because of an invalid argument. See additional error messages for details. cpp-header-image value exceeds maximum allowable length.
Error Message Reference Express Checkout API Errors TABLE B.3 SetExpressCheckout API Errors Error Code Short Message Long Message Correcting This Error... 10539 Payment declined by your Risk Controls settings: PayPal Risk Model. Payment declined by your Risk Controls settings: PayPal Risk Model.
Error Message Reference Express Checkout API Errors TABLE B.4 GetExpressCheckoutDetails API Errors Error Code Short Message 10001 ButtonSource value truncated. The transaction could not be loaded 10001 ButtonSource value truncated. The transaction could not be loaded 10004 Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details.
Error Message Reference Express Checkout API Errors TABLE B.4 GetExpressCheckoutDetails API Errors Error Code Short Message Long Message 10007 Permission denied You do not have permissions to make this API call 10007 Permission denied You do not have permission to get the details of this transaction 10007 Permission denied You do not have permissions to make this API call 10408 Express Checkout token is missing. Express Checkout token is missing.
Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code Short Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details. 10004 Transaction refused because of an invalid argument. See additional error messages for details.
Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors 78 Error Code Short Message 10413 Long Message Correcting This Error... Transaction refused because of an invalid argument. See additional error messages for details. The totals of the cart item amounts do not match order amounts. If you include any of the following element values with DoExpressCheckoutPayment, the sum of their values must equal the value of OrderTotal.
Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code Short Message 10417 Long Message Correcting This Error... Transaction cannot complete. The transaction cannot complete successfully. Instruct the customer to use an alternative payment method. It is possible that the payment method the customer chooses on PayPal might not succeed when you send DoExpressCheckoutPayment.
Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors 80 Error Code Short Message 10421 Long Message Correcting This Error... This Express Checkout session belongs to a different customer. This Express Checkout session belongs to a different customer. Token value mismatch. When your customer logs into PayPal, the PayPal PayerID is associated with the Express Checkout token. This error is caused by mixing tokens for two different PayerIDs.
Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code Short Message 10431 Item amount is invalid. Item amount is invalid. 10432 Transaction refused because of an invalid argument. See additional error messages for details. Invoice ID value exceeds maximum allowable length. 10433 Transaction refused because of an invalid argument. See additional error messages for details. Value of OrderDescription element has been truncated.
Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors 82 Error Code Short Message Long Message 10442 ButtonSource value truncated. The ButtonSource element value exceeds maximum allowable length. 10443 Transaction refused because of an invalid argument. See additional error messages for details. This transaction cannot be completed with PaymentAction of Order. 10444 Transaction refused because of an invalid argument.
Error Message Reference Express Checkout API Errors TABLE B.5 DoExpressCheckoutPayment API Errors Error Code Short Message 10539 Payment declined by your Risk Controls settings: PayPal Risk Model. Payment declined by your Risk Controls settings: PayPal Risk Model.
Error Message Reference RefundTransaction API Errors RefundTransaction API Errors TABLE B.6 RefundTransaction API Errors 84 Error Code Short Message Long Message 10001 Internal Error Internal Error 10001 Internal Error Warning an internal error has occurred. The transaction id may not be correct 10001 ButtonSource value truncated. The transaction could not be loaded 10001 Internal Error Internal Error 10004 Transaction refused because of an invalid argument.
Error Message Reference RefundTransaction API Errors TABLE B.6 RefundTransaction API Errors Error Code Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. The partial refund amount must be a positive amount 10004 Transaction refused because of an invalid argument. See additional error messages for details. You can not specify a partial amount with a full refund 10004 Transaction refused because of an invalid argument.
Error Message Reference RefundTransaction API Errors TABLE B.
Error Message Reference TransactionSearch API Errors TABLE B.
Error Message Reference TransactionSearch API Errors TABLE B.2 Error Code 88 TransactionSearch API Errors Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. Start date is invalid 10004 Transaction refused because of an invalid argument. See additional error messages for details. End date is invalid 10004 Transaction refused because of an invalid argument. See additional error messages for details.
Error Message Reference GetTransactionDetails API Errors TABLE B.2 Error Code TransactionSearch API Errors Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. The transaction id is not valid 10007 Permission denied You do not have permissions to 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.
Error Message Reference MassPay API Errors TABLE B.8 MassPay API Errors Error Code 90 Short Message Long Message 10001 Transaction refused because of an invalid argument. See additional error messages for details. The masspay receiver_type is not a recognizable type 10002 Account locked The user account is locked 10004 Transaction refused because of an invalid argument. See additional error messages for details.
Error Message Reference MassPay API Errors TABLE B.8 MassPay API Errors Error Code Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. The currency is missing 10004 Transaction refused because of an invalid argument. See additional error messages for details. Currency is not supported 10004 Transaction refused because of an invalid argument. See additional error messages for details.
Error Message Reference MassPay API Errors TABLE B.8 MassPay API Errors Error Code 92 Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. The unique id string length exceeds the maximum limit of 30 characters 10004 Transaction refused because of an invalid argument. See additional error messages for details. The unique id string contains a space as a character 10004 Transaction refused because of an invalid argument.
Error Message Reference MassPay API Errors TABLE B.
Error Message Reference MassPay API Errors 94 March 2007 Name-Value Pair API Developer Guide and Reference
C NVP API Web Samples This chapter describes the NVP API Web Samples which access the NVP API directly.
NVP API Web Samples Descriptions of the Samples The primary files for this sample are: TABLE C.1 Express Checkout Files File Description SetExpressCheckout.ext 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 paymentType 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.
NVP API Web Samples Descriptions of the Samples 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 DoExpressCheckoutPayment 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.
NVP API Web Samples Common Files The following files are common to the samples. TABLE C.3 Common Files File Description index.html Default.htm The main web page with links to each sample. 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.
NVP API Web Samples Samples Using PHP 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 enabled 4.4.2 or greater http://www.php.net/downloads.php Apache HTTP Server 1.3.17 or greater http://httpd.apache.org/ You must install and configure PHP with the Apache HTTP Server.
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.
NVP API Web Samples 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.
NVP API Web Samples Samples Using ColdFusion 102 April 2007 Name-Value Pair API Developer Guide and Reference
D The Java SDK This section describes how to use the Java SDK for the NVP API and includes the following topics: z “Installing the Java SDK” on page 103 z “Profiles” on page 106 z “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.
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 1 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.
The Java SDK 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.
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: z z z z z A PayPal API username and password. If you are using API certificates, the path to the API certificate in P12 format and the private key password to that certificate. If you are using API signatures, the signature string.
The Java SDK 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).
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_api1.sdk.com API password QFZCWN5HZM8VBG7Q API signature A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU IMPO RTANT: You must protect the API signature values in your implementation.
E The ASP.NET SDK This section describes how to use the ASP.NET SDK for the NVP API and includes the following topics: z “Installing the ASP.NET SDK” on page 109 z “Profiles” on page 113 z “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 with the following standards. TABLE E.
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.
The ASP.NET SDK Installing the ASP.NET SDK SDK Directories and Optional Configurations The SDK components are organized into different subdirectories, as shown in Table E.3, “PayPal SDK Directories and Contents.” TABLE E.3 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 sdkseller_api1.sdk.
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.
The ASP.NET SDK Complete SDK and API Class Documentation Enabling Proxy Support 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.
The ASP.NET SDK Profiles z z The URL to which the button form POSTs 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.
The ASP.NET SDK Sample Applications Sample Applications The PayPal SDK includes sample applications in the SDK_root\samples\ASPNET folder. The samples\ASPNET folder is divided into subfolders by products. TABLE E.6 Samples by Product 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.
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_api1.sdk.
F Country Codes N O T E : This table lists country codes defined by ISO 3166-1.
Country Codes 118 Country Code Country Code CHILE CL FK CHINA CN FALKLAND ISLANDS (MALVINAS) CHRISTMAS ISLAND CX FAROE ISLANDS FO COCOS (KEELING) ISLANDS CC FIJI FJ COLOMBIA CO FINLAND FI COMOROS KM FRANCE FR CONGO CG FRENCH GUIANA GF CONGO, THE DEMOCRATIC REPUBLIC OF THE CD FRENCH POLYNESIA PF TF COOK ISLANDS CK FRENCH SOUTHERN TERRITORIES COSTA RICA CR GABON GA COTE D'IVOIRE CI GAMBIA GM CROATIA HR GEORGIA GE CUBA CU GERMANY DE CYPRUS CY GHANA GH
Country Code Country Code HEARD ISLAND AND MCDONALD ISLANDS HM LATVIA LV LEBANON LB HOLY SEE (VATICAN CITY STATE) VA LESOTHO LS HONDURAS HN LIBERIA LR HONG KONG HK LIBYAN ARAB JAMAHIRIYA LY HUNGARY HU LIECHTENSTEIN LI ICELAND IS LITHUANIA LT INDIA IN LUXEMBOURG LU INDONESIA ID MACAO MO IRAN, ISLAMIC REPUBLIC OF IR MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF MK IRAQ IQ MADAGASCAR MG IRELAND IE MALAWI MW ISLE OF MAN IM MALAYSIA MY ISRAEL IL MALDIVES MV
Country Codes 120 Country Code Country Code MOROCCO MA PHILIPPINES PH MOZAMBIQUE MZ PITCAIRN PN MYANMAR MM POLAND PL NAMIBIA NA PORTUGAL PT NAURU NR PUERTO RICO PR NEPAL NP QATAR QA NETHERLANDS NL REUNION RE NETHERLANDS ANTILLES AN ROMANIA RO NEW CALEDONIA NC RUSSIAN FEDERATION RU NEW ZEALAND NZ RWANDA RW NICARAGUA NI SAINT HELENA SH NIGER NE SAINT KITTS AND NEVIS KN NIGERIA NG SAINT LUCIA LC NIUE NU SAINT PIERRE AND MIQUELON PM NORFOLK ISLAND NF
Country Code Country Code SOLOMON ISLANDS SB UGANDA UG SOMALIA SO UKRAINE UA SOUTH AFRICA ZA UNITED ARAB EMIRATES AE SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS GS UNITED KINGDOM GB UNITED STATES US SPAIN ES LK UNITED STATES MINOR OUTLYING ISLANDS UM SRI LANKA SUDAN SD URUGUAY UY SURINAME SR UZBEKISTAN UZ SVALBARD AND JAN MAYEN SJ VANUATU VU SWAZILAND SZ VENEZUELA VE SWEDEN SE VIET NAM VN SWITZERLAND CH VIRGIN ISLANDS, BRITISH VG SYRIAN ARAB REPUBLIC SY V
Country Codes 122
Index A C 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.
Index EUR 35 Euro 35 EWP profile defined 106, 113 EWPProfile interface 107, 114 EXCHANGERATE 48, 57 Expired 57 Express Checkout 107, 115 J Japanese Yen 36 Java Development Kit 1.
Index DoExpressCheckoutPayment 44 GetExpressCheckoutDetails 41 GetTransactionDetails 54 MassPay 60 RefundTransaction 50 SetExpressCheckout 36 TransactionSearch 51 Microsoft .NET 1.
Index SUBSCRIPTIONID 59 Success (transaction status) 53 successResponseFields, defined 15 SUFFIX 42, 52, 55 Swedish Krona 36 Swiss Franc 35 system store 116 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_api1.sdk.
Index ColdFusion 13 Java 13 PHP 13 USD 36 USER 14 USERNAME 59 UTC/GMT 53 V VERSION 15, 16, 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.