2009

ManualsBrandsPayPal ManualsApplicationsName-Value Pair API

Table Of Contents

Name-Value Pair API Developer Guide

Name-Value Pair API

Developer Guide

Last updated: 08 April 2009

Summary of content (243 pages)

PAGE 1
Name-Value Pair API Developer Guide Last updated: 08 April 2009
PAGE 2
Name-Value Pair API Developer Guide Document Number: 100018.en_US-20090408 © 2009 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. Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l. et Cie., S.C.
PAGE 3
Contents Preface 9 This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Chapter 1 PayPal NVP API Overview . . . . . . . . . . . . . . . . . . 11 Introducing the PayPal NVP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 4
Contents DoReauthorization Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 DoReauthorization Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 DoVoid API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 DoVoid Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 DoVoid Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Chapter 3 DoDirectPayment API . . . .
PAGE 5
Contents Chapter 8 TransactionSearch API . . . . . . . . . . . . . . . . . . . 91 TransactionSearch Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 TransactionSearch Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Chapter 9 Recurring Payments and Reference Transactions API Operations95 CreateRecurringPaymentsProfile API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 CreateRecurringPaymentsProfile Request . . . . . . . . . . . . . . .
PAGE 6
Contents Chapter 11 ManagePendingTransactionStatus API . . . . . . . . . . 151 ManagePendingTransactionStatus Request . . . . . . . . . . . . . . . . . . . . . . . . .151 ManagePendingTransactionStatus Response . . . . . . . . . . . . . . . . . . . . . . . .151 Chapter 12 GetBalance API . . . . . . . . . . . . . . . . . . . . . . 153 GetBalance Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153 GetBalance Response . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 7
Contents Chapter C State and Province Codes . . . . . . . . . . . . . . . . . 235 Chapter D Currency Codes . . . . . . . . . . . . . . . . . . . . . . 239 Chapter E AVS and CVV2 Response Codes . . . . . . . . . . . . . 241 AVS Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241 CVV2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 8
Contents 8 08 April 2009 Name-Value Pair API Developer Guide
PAGE 9
Preface This Document The Name-Value Pair API Developer Guide describes the PayPal Name-Value Pair API. Intended Audience The Name-Value Pair API Developer Guide is written for web developers who are implementing solutions using the Name-Value Pair API. Revision History Revision history for Name-Value Pair API Developer Guide. TABLE P.1 Revision History Date Description 08 April 2009 Updated information for 57.0: Express Checkout Callback API. 26 Nov. 2008 Updated information for 55.0. 23 Sept.
PAGE 10
Revision History TABLE P.1 Revision History Date September 2007 Description z z z 10 Update eBay auctions for Express Checkout section Added fields for the giropay payment method to Express Checkout APIs Added Direct Payment error 10571. August 2007 Added recurring payments concepts, modified SetExpressCheckout, DoExpressCheckoutPayment, DoReferenceTransaction, and added additional DoReferenceTransaction error codes.
PAGE 11
1 PayPal NVP API Overview This overview describes the PayPal Name-Value Pair (NVP) API at a high level. z “Introducing the PayPal NVP API” on page 11 z “Basic Steps” on page 12 z “Taking Your Application Live” on page 13 z “Technical Details” on page 14 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.
PAGE 12
PayPal NVP API Overview Basic Steps 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 API. 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.
PAGE 13
PayPal NVP API Overview Taking Your Application Live 3. Post the NVP request to the PayPal Sandbox as described in “Posting Using HTTPS” on page 18. 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 14. 3. Take appropriate action for successful and failed reponses.
PAGE 14
PayPal NVP API Overview Technical Details z The server address in the URL. (See “Posting Using HTTPS” on page 18.) z API credentials you set up in “Set Up API Credentials” on page 13. 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.
PAGE 15
PayPal NVP API Overview Technical Details URL-Encoding Methods Language ASP.NET Classic ASP Java PHP ColdFusion Method Encode System.Web.HttpUtility.UrlEncode(buffer, Encoding.Default) Decode System.Web.HttpUtility.UrlDecode(buffer, Encoding.Default) Encode Server.URLEncode Decode No built-in function. Several implementation examples are available on the Internet. Encode java.net.URLEncoder.encode Decode java.net.URLDecoder.
PAGE 16
PayPal NVP API Overview Technical Details 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. Security Parameters The security parameters are described below. These are your PayPal API credentials. Required Security Parameters: API Credentials Parameter Value USER (Required) Your PayPal API Username. PWD (Required) Your PayPal API Password.
PAGE 17
PayPal NVP API Overview Technical Details 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. General Format of a Successful Response Success Response Fields ACK=Success&TIMESTAMP=date/timeOfResponse &CORRELATIONID=debuggingToken&VERSION=... &BUILD=buildNumber API Response Fields &NAME1=value1&NAME2=value2&NAME3=value3&... Each response includes the ACK field.
PAGE 18
PayPal NVP API Overview Posting Using HTTPS 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.paypal.
PAGE 19
2 Authorization and Capture API Operation Reference This chapter describes the PayPal API operations related to delayed payment settlement: z “DoCapture API” on page 19 z “DoAuthorization API” on page 23 z “DoReauthorization API” on page 24 z “DoVoid API” on page 25 DoCapture API Capture an authorized payment.
PAGE 20
Authorization and Capture API Operation Reference DoCapture API DoCapture Request DoCapture Request Fields Field Description METHOD (Required) Must be DoCapture. AUTHORIZATIONID (Required) The authorization identification number of the payment you want to capture. This is the transaction id returned from DoExpressCheckoutPayment or DoDirectPayment. Character length and limits: 19 single-byte characters maximum. AMT (Required) Amount to capture.
PAGE 21
Authorization and Capture API Operation Reference DoCapture API Field Description SOFTDESCRIPTOR (Optional) The soft descriptor is a per transaction description of the payment that is passed to the consumer’s credit card statement.
PAGE 22
Authorization and Capture API Operation Reference DoCapture API Do Capture Response Fields Field Description AUTHORIZATIONID The authorization identification number you specified in the request. Character length and limits: 19 single-byte characters maximum. PayerInfo Type Fields Field Description EMAIL Email address of payer. Character length and limitations: 127 single-byte characters. PAYERID Unique PayPal customer account identification number.
PAGE 23
Authorization and Capture API Operation Reference DoAuthorization API Field Description SHIPTOSTATE State or province. Character length and limitations: 40 single-byte characters. Required for U.S. addresses only. SHIPTOZIP U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters. SHIPTOCOUNTRYCODE Country code. Character limit: Two single-byte characters. Payer Name Fields Field Description SALUTATION Payer’s salutation.
PAGE 24
Authorization and Capture API Operation Reference DoReauthorization API DoAuthorization Request DoAuthorization Request Fields Field Description METHOD (Required) Must be DoAuthorization. TRANSACTIONID (Required) The value of the order’s transaction identification number returned by PayPal. Character length and limits: 19 single-byte characters maximum. AMT (Required) Amount to authorize. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency. No currency symbol.
PAGE 25
Authorization and Capture API Operation Reference DoVoid API DoReauthorization Request DoReauthorization Request Fields Field Description METHOD (Required) Must be DoReauthorization. AUTHORIZATIONID (Required) The value of a previously authorized transaction identification number returned by PayPal. Character length and limits: 19 single-byte characters maximum. AMT (Required) Amount to reauthorize. Limitations: Value is a positive number which cannot exceed $10,000 USD in any currency.
PAGE 26
Authorization and Capture API Operation Reference DoVoid API DoVoid Request DoVoid Request Fields Field Description METHOD (Required) Must be DoVoid. AUTHORIZATIONID (Required) The value of the original authorization identification number returned by a PayPal product. IMPORTANT: If you are voiding a transaction that has been reauthorized, use the ID from the original authorization, and not the reauthorization. Character length and limits: 19 single-byte characters.
PAGE 27
3 DoDirectPayment API Process a credit card payment.
PAGE 28
DoDirectPayment API DoDirectPayment Request DoDirectPayment Request Fields Field Description METHOD (Required) Must be DoDirectPayment. PAYMENTACTION (Optional) How you want to obtain payment: z Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. z Sale indicates that this is a final sale for which you are requesting payment. Character length and limit: Up to 13 single-byte alphabetic characters.
PAGE 29
DoDirectPayment API DoDirectPayment Request Field Description EXPDATE Credit card expiration date. This field is required if you are using recurring payments with direct payments. Format: MMYYYY Character length and limitations: Six single-byte alphanumeric characters, including leading zero. CVV2 Card Verification Value, version 2. Your Merchant Account settings determine whether this field is required. Character length for Visa, MasterCard, and Discover: exactly three digits.
PAGE 30
DoDirectPayment API DoDirectPayment Request PayerInfo Type Fields Field Description 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. Valid values are: z verified z unverified Character length and limitations: 10 single-byte alphabetic characters.
PAGE 31
DoDirectPayment API DoDirectPayment Request Field Description STATE (Required) State or province. Character length and limitations: 40 single-byte characters. COUNTRYCODE (Required) Country code. Character limit: Two single-byte characters. ZIP (Required) U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters. PHONENUM (Optional) Phone number. Character length and limit: 20 single-byte characters.
PAGE 32
DoDirectPayment API DoDirectPayment Request Payment Details Type Fields Field Description AMT (Required) The total cost of the transaction 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. If the transaction includes one or more one-time purchases, this field must be equal to the sum of the purchases.
PAGE 33
DoDirectPayment API DoDirectPayment Request Field Description HANDLINGAMT (Optional) Total handling costs for this order. TAXAMT 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: If you specify a value for HANDLINGAMT, you must also specify a value for ITEMAMT.
PAGE 34
DoDirectPayment API DoDirectPayment Request Payment Details Item Type Fields Field Description L_NAMEn (Optional) Item name. These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1). Character length and limitations: 127 single-byte characters L_DESCn (Optional) Item description. Character length and limitations: 127 single-byte characters L_AMTn (Optional) Cost of item. These parameters must be ordered sequentially beginning with 0 (for example L_AMT0, L_AMT1).
PAGE 35
DoDirectPayment API DoDirectPayment Request Field Description L_ITEMWIDTHVALUEn, L_ITEMWIDTHUNITn (Optional) Item width corresponds to the width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query. These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).
PAGE 36
DoDirectPayment API DoDirectPayment Response EbayItemPaymentDetailsItemType Fields Field Description L_EBAYITEMNUMBERn (Optional) Auction item number. These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1). Character length: 765 single-byte characters L_EBAYITEMAUCTIONTX NIDn (Optional) Auction transaction identification number.
PAGE 37
DoDirectPayment API DoDirectPayment Response DoDirectPayment Response Fields Field Description TRANSACTIONID Unique transaction ID of the payment. NOTE: If the PaymentAction of the request was Authorization, the value of TransactionID is your AuthorizationID for use with the Authorization & Capture APIs. Character length and limitations: 19 single-byte characters. AMT This value is the amount of the payment as specified by you on DoDirectPaymentRequest for reference transactions with direct payments.
PAGE 38
DoDirectPayment API DoDirectPayment Response 38 08 April 2009 Name-Value Pair API Developer Guide
PAGE 39
4 Express Checkout API Operations This chapter describes the PayPal API operations related to Express Checkout transactions: z “SetExpressCheckout API” on page 43 z “GetExpressCheckoutDetails API” on page 54 z “DoExpressCheckoutPayment API” on page 63 Callback API Updates the PayPal Review page with shipping options, insurance, and tax information.
PAGE 40
Express Checkout API Operations Callback API Callback Request Callback Request Fields Field Description METHOD (Required) Must be Callback. TOKEN (Optional) A timestamped token, the value of which was returned by SetExpressCheckout response. Character length and limitations: 20 single-byte characters CURRENCYCODE (Required) The three-character currency code for the transaction from the Express Checkout API.
PAGE 41
Express Checkout API Operations Callback API Field Description L_ITEMHEIGHTVALUEn, L_ITEMHEIGHTUNITn The height of the item. You can pass this data to the shipping carrier as is without having to make an additional database query. These parameters must be ordered sequentially beginning with 0 (for example, L_ITEMHEIGHTVALUE0, ITEMHEIGHTVALUE1). L_ITEMWIDTHVALUEn, L_ITEMWIDTHUNITn The width of the item.
PAGE 42
Express Checkout API Operations Callback API Callback Response Callback Response Fields Field Description METHOD (Required) The method sent to the PayPal server. The value is always CallbackResponse. OFFERINSURANCEOPTIO N (Optional) Indicates whether or not PayPal should display insurance in a drop-down list on the Review page. When the value is true, PayPal displays the drop-down with the associated amount and the string ‘Yes.
PAGE 43
Express Checkout API Operations SetExpressCheckout API Field Description OFFERINSURANCEOPTIO N (Optional) Indicates whether or not PayPal should display insurance in a drop-down list on the Review page. When the value is true, PayPal displays the drop-down with the associated amount and the string ‘Yes.’ SetExpressCheckout API Initiates an Express Checkout transaction. Optionally, the SetExpressCheckout API operation can set up billing agreements for reference transactions and recurring payments.
PAGE 44
Express Checkout API Operations SetExpressCheckout API SetExpressCheckout Request Fields Field Description METHOD (Required) Must be SetExpressCheckout. TOKEN (Optional) A timestamped token, the value of which was returned by SetExpressCheckout response. Character length and limitations: 20 single-byte characters MAXAMT (Optional) The expected maximum total amount of the complete order, including shipping cost and tax charges.
PAGE 45
Express Checkout API Operations SetExpressCheckout API Field Description ALLOWNOTE (Optional) The value 1 indicates that the customer may enter a note to the merchant on the PayPal page during checkout. The note is returned in the GetExpressCheckoutDetails response and the DoExpressCheckoutPayment response. Character length and limitations: One single-byte numeric character.
PAGE 46
Express Checkout API Operations SetExpressCheckout API Field Description HDRBACKCOLOR (Optional) Sets the background color for the header of the payment page. By default, the color is white. Character length and limitation: Six character HTML hexadecimal color code in ASCII. PAYFLOWCOLOR (Optional) Sets the background color for the payment page. By default, the color is white. Character length and limitation: Six character HTML hexadecimal color code in ASCII.
PAGE 47
Express Checkout API Operations SetExpressCheckout API Field Description GIROPAYCANCELURL (Optional) The URL on the merchant site to redirect to after a successful giropay payment. Use this field only if you are using giropay or bank transfer payment methods in Germany. BANKTXNPENDINGURL (Optional) The URL on the merchant site to transfer to after a bank transfer payment. Use this field only if you are using giropay or bank transfer payment methods in Germany.
PAGE 48
Express Checkout API Operations SetExpressCheckout API Address Fields Field Description NAME Person’s name associated with this shipping address. Required if using a shipping address. Character length and limitations: 32 single-byte characters. SHIPTOSTREET First street address. Required if using a shipping address. Character length and limitations: 100 single-byte characters. SHIPTOSTREET2 (Optional) Second street address. Character length and limitations: 100 single-byte characters.
PAGE 49
Express Checkout API Operations SetExpressCheckout API Field Description SHIPPINGAMT (Optional) Total shipping costs for this order. INSURANCEAMT 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.
PAGE 50
Express Checkout API Operations SetExpressCheckout API Field Description INVNUM (Optional) Your own invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters BUTTONSOURCE (Optional) An identification code for use by third-party applications to identify transactions. Character length and limitations: 32 single-byte alphanumeric characters NOTIFYURL (Optional) Your URL for receiving Instant Payment Notification (IPN) about this transaction.
PAGE 51
Express Checkout API Operations SetExpressCheckout API Payment Details Item Type Fields Field Description L_NAMEn (Optional) Item name. These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1). Character length and limitations: 127 single-byte characters L_DESCn (Optional) Item description. Character length and limitations: 127 single-byte characters L_AMTn (Optional) Cost of item.
PAGE 52
Express Checkout API Operations SetExpressCheckout API 52 Field Description L_ITEMWIDTHVALUEn, L_ITEMWIDTHUNITn (Optional) Item width corresponds to the width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query. These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).
PAGE 53
Express Checkout API Operations SetExpressCheckout API EbayItemPaymentDetailsItemType Fields Field Description L_EBAYITEMNUMBERn (Optional) Auction item number. These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1). Character length: 765 single-byte characters L_EBAYITEMAUCTIONTX NIDn (Optional) Auction transaction identification number.
PAGE 54
Express Checkout API Operations GetExpressCheckoutDetails API Billing Agreement Details Fields Field Description L_BILLINGTYPEn (Required) Type of billing agreement. For recurring payments, this field must be set to RecurringPayments. In this case, you can specify up to ten billing agreements. NOTE: Other defined values are not valid. L_BILLINGAGREEMENTD ESCRIPTIONn Description of goods or services associated with the billing agreement, which is required for each recurring payment billing agreement.
PAGE 55
Express Checkout API Operations GetExpressCheckoutDetails API GetExpressCheckoutDetails Request GetExpressCheckoutDetails Request Fields Field Description METHOD (Required) Must be GetExpressCheckoutDetails. TOKEN (Required) A timestamped token, the value of which was returned by SetExpressCheckout response.
PAGE 56
Express Checkout API Operations GetExpressCheckoutDetails API 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 CUSTOM A free-form field for your own use, as set by you in the Custom element of SetExpressCheckout request.
PAGE 57
Express Checkout API Operations GetExpressCheckoutDetails API Field Description 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 BUSINESS Payer’s business name.
PAGE 58
Express Checkout API Operations GetExpressCheckoutDetails API Payer Name Fields Field Description SALUTATION Payer’s salutation. Character length and limitations: 20 single-byte characters FIRSTNAME Payer’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.
PAGE 59
Express Checkout API Operations GetExpressCheckoutDetails API Payment Details Type Fields Field Description AMT (Required) The total cost of the transaction 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. If the transaction includes one or more one-time purchases, this field must be equal to the sum of the purchases.
PAGE 60
Express Checkout API Operations GetExpressCheckoutDetails API Field Description HANDLINGAMT (Optional) Total handling costs for this order. TAXAMT 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.
PAGE 61
Express Checkout API Operations GetExpressCheckoutDetails API Payment Details Item Type Fields Field Description L_NAMEn (Optional) Item name. These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1). Character length and limitations: 127 single-byte characters L_AMTn (Optional) Cost of item. These parameters must be ordered sequentially beginning with 0 (for example L_AMT0, L_AMT1).
PAGE 62
Express Checkout API Operations GetExpressCheckoutDetails API 62 Field Description L_ITEMWIDTHVALUEn, L_ITEMWIDTHUNITn (Optional) Item width corresponds to the width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query. These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).
PAGE 63
Express Checkout API Operations DoExpressCheckoutPayment API User Selected Options Type Fields Field Description SHIPPINGCALCULATION MODE (Optional) Describes how the options that were presented to the user were determined. Is one of the following values: z API - Callback z API - Flatrate INSURANCEOPTIONSELE CTED (Optional) The Yes/No option that you chose for insurance. SHIPPINGOPTIONISDEF AULT (Optional) Is true if the buyer chose the default shipping option.
PAGE 64
Express Checkout API Operations DoExpressCheckoutPayment API DoExpressCheckoutPayment Request 64 z DoExpressCheckout Request Fields z Payment Details Type Fields z eBay Item Payment Details Item Type Fields z Payment Details Item Type Fields z Address Fields 08 April 2009 Name-Value Pair API Developer Guide
PAGE 65
Express Checkout API Operations DoExpressCheckoutPayment API DoExpressCheckoutPayment Request Fields Field Description METHOD (Required) Must be DoExpressCheckoutPayment. TOKEN (Required) The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request.
PAGE 66
Express Checkout API Operations DoExpressCheckoutPayment API Field Description ITEMAMT (Optional) Sum of cost of all items in this order. 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: SHIPPINGAMT INSURANCEAMT (Optional) Total shipping costs for this order.
PAGE 67
Express Checkout API Operations DoExpressCheckoutPayment API Field Description DESC (Optional) Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters CUSTOM (Optional) A free-form field for your own use. Character length and limitations: 256 single-byte alphanumeric characters INVNUM (Optional) Your own invoice or tracking number.
PAGE 68
Express Checkout API Operations DoExpressCheckoutPayment API Payment Details Item Type Fields Field Description L_NAMEn (Optional) Item name. These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1). Character length and limitations: 127 single-byte characters L_DESCn (Optional) Item description. Character length and limitations: 127 single-byte characters L_AMTn (Optional) Cost of item.
PAGE 69
Express Checkout API Operations DoExpressCheckoutPayment API Field Description L_ITEMWIDTHVALUEn, L_ITEMWIDTHUNITn (Optional) Item width corresponds to the width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query. These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).
PAGE 70
Express Checkout API Operations DoExpressCheckoutPayment API User Selected Options Type Fields Field Description SHIPPINGCALCULATION MODE (Optional) Describes how the options that were presented to the user were determined. Is one of the following values: z API - Callback z API - Flatrate INSURANCEOPTIONSELE CTED (Optional) The Yes/No option that you chose for insurance. SHIPPINGOPTIONISDEF AULT (Optional) Is true if the buyer chose the default shipping option.
PAGE 71
Express Checkout API Operations DoExpressCheckoutPayment API Field Description SHIPTOSTREET2 (Optional) Second street address. Character length and limitations: 100 single-byte characters. SHIPTOCITY Name of city. Required if using a shipping address. Character length and limitations: 40 single-byte characters. SHIPTOSTATE State or province. Required if using a shipping address. Character length and limitations: 40 single-byte characters. SHIPTOZIP U.S.
PAGE 72
Express Checkout API Operations DoExpressCheckoutPayment API DoExpressCheckoutPayment 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 NOTE The text entered by the buyer on the PayPal website if the ALLOWNOTE field was set to 1 in SetExpressCheckout.
PAGE 73
Express Checkout API Operations DoExpressCheckoutPayment API Field Description TRANSACTIONTYPE The type of transaction Character length and limitations:15 single-byte characters Valid values: z cart z express-checkout PAYMENTTYPE Indicates whether the payment is instant or delayed.
PAGE 74
Express Checkout API Operations DoExpressCheckoutPayment API 74 Field Description PENDINGREASON The reason the payment is pending: z none: No pending reason. z 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.
PAGE 75
5 GetTransactionDetails API Obtain information about a specific transaction. z “GetTransactionDetails Request” on page 75 z “GetTransactionDetails Response” on page 75 GetTransactionDetails Request GetTransactionDetails Request Fields Field Description METHOD Must be GetTransactionDetails. TRANSACTIONID (Required) Unique identifier of a transaction. NOTE: The details for some kinds of transactions cannot be retrieved with GetTransactionDetails.
PAGE 76
GetTransactionDetails API GetTransactionDetails Response Receiver Information Fields Field Description 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).
PAGE 77
GetTransactionDetails API GetTransactionDetails Response Address Fields Field Description ADDRESSOWNER eBay company that maintains this address. Valid values are: z eBay z PayPal ADDRESSSTATUS Status of street address on file with PayPal. Valid values are: z none z Confirmed z Unconfirmed 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.
PAGE 78
GetTransactionDetails API GetTransactionDetails Response Field PARENTTRANSACTIONID Description z z z z z z z Parent or related transaction identification number. This field is populated for the following transaction types: Reversal. Capture of an authorized transaction. Reversal. Reauthorization of a transaction. Capture of an order. The value of ParentTransactionID is the original OrderID. Authorization of an order. The value of ParentTransactionID is the original OrderID.
PAGE 79
GetTransactionDetails API GetTransactionDetails Response Field Description 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. EXCHANGERATE Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency.
PAGE 80
GetTransactionDetails API GetTransactionDetails Response Field Description PENDINGREASON NOTE: PendingReason is returned in the response only if PaymentStatus is Pending. The reason the payment is pending: z none: No pending reason. z 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.
PAGE 81
GetTransactionDetails API GetTransactionDetails Response Field Description PROTECTIONELIGIBILI TY The the kind of seller protection in force for the transaction, which is one of the following values: z Eligible – Seller is protected by PayPal's Seller Protection Policy for Unauthorized Payments and Item Not Received z PartiallyEligible – Seller is protected by PayPal's Seller Protection Policy for Item Not Received z Ineligible – Seller is not protected under the Seller Protection Policy Name-Value Pai
PAGE 82
GetTransactionDetails API GetTransactionDetails Response Payment Item Information Fields Field Description 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 NOTE Memo entered by your customer in PayPal Website Payments note field.
PAGE 83
GetTransactionDetails API GetTransactionDetails Response Field Description MULTIITEM Counter used for multi-item auction payments Subscription Terms Fields Field Description AMT The amount subscriber is to be charged in one payment. Character length and limitations: no limit PERIOD The period of time that the subscriber will be charged.
PAGE 84
GetTransactionDetails API GetTransactionDetails Response 84 08 April 2009 Name-Value Pair API Developer Guide
PAGE 85
6 MassPay API Make a payment to one or more PayPal account holders.
PAGE 86
MassPay API MassPay Request MassPay Request Fields Field Description METHOD (Required) Must be MassPay. EMAILSUBJECT (Optional) The subject line of the email that PayPal sends when the transaction is completed. The subject line is the same for all recipients. Character length and limitations: 255 single-byte alphanumeric characters. CURRENCYCODE A three-character currency code. See “Currency Codes” on page 239.
PAGE 87
MassPay API MassPay Response MassPay Response The fields in the response are the standard response header fields.
PAGE 88
MassPay API MassPay Response 88 08 April 2009 Name-Value Pair API Developer Guide
PAGE 89
7 RefundTransaction API Issue a refund to the PayPal account holder associated with a transaction. z “RefundTransaction Request” on page 89 z “RefundTransaction Response” on page 89 RefundTransaction Request RefundTransaction Request Fields Field Description METHOD (Required) Must be RefundTransaction. TRANSACTIONID (Required) Unique identifier of a transaction. Character length and limitations: 17 single-byte alphanumeric characters.
PAGE 90
RefundTransaction API RefundTransaction Response 90 08 April 2009 Name-Value Pair API Developer Guide
PAGE 91
8 TransactionSearch API Search transaction history for transactions that meet the specified criteria.
PAGE 92
TransactionSearch API TransactionSearch Request TransactionSearch Request Fields Field Description METHOD (Required) Must be TransactionSearch. STARTDATE (Required) The earliest transaction date at which to start the search. No wildcards are allowed. The value must be in UTC/GMT format. ENDDATE (Optional) The latest transaction date to be included in the search. EMAIL (Optional) Search by the buyer’s email address. Character length and limitations: 127 single-byte alphanumeric characters.
PAGE 93
TransactionSearch API TransactionSearch Request Field Description TRANSACTIONCLASS (Optional) Search by classification of transaction. Some kinds of possible classes of transactions are not searchable with this field. You cannot search for bank transfer withdrawals, for example.
PAGE 94
TransactionSearch API TransactionSearch Response Payer Name Fields Field Description SALUTATION Payer’s salutation. Character length and limitations: 20 single-byte characters. FIRSTNAME Payer’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.
PAGE 95
9 Recurring Payments and Reference Transactions API Operations This chapter describes the PayPal API operations related to recurring payments and reference transactions: z “CreateRecurringPaymentsProfile API” on page 95 z “GetRecurringPaymentsProfileDetails API” on page 106 z “ManageRecurringPaymentsProfileStatus API” on page 113 z “BillOutstandingAmount API” on page 114 z “UpdateRecurringPaymentsProfile API” on page 115 z “SetCustomerBillingAgreement API” on page 123 z “GetBillingAgreementCu
PAGE 96
Recurring Payments and Reference Transactions API Operations CreateRecurringPaymentsProfile API 96 z Billing Period Details z Activation Details z Ship To Address z Credit Card Details z Payer Information z Payer Name z Billing Address 08 April 2009 Name-Value Pair API Developer Guide
PAGE 97
Recurring Payments and Reference Transactions API Operations CreateRecurringPaymentsProfile API CreateRecurringPaymentsProfile Request Fields Field Description METHOD (Required) Must be CreateRecurringPaymentsProfile. TOKEN A timestamped token, the value of which was returned in the response to the first call to SetExpressCheckout. You can also use the token returned in the SetCustomerBillingAgreement response. Either this token or a credit card number is required.
PAGE 98
Recurring Payments and Reference Transactions API Operations CreateRecurringPaymentsProfile API 98 Field Description AUTOBILLAMT (Optional) This field indicates whether you would like PayPal to automatically bill the outstanding balance amount in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments that have yet to be successfully paid. Valid values: Must be NoAutoBill or AddToNextBilling.
PAGE 99
Recurring Payments and Reference Transactions API Operations CreateRecurringPaymentsProfile API Billing Period Details Type Field Description BILLINGPERIOD (Required) Unit for billing during this subscription period. One of the following values: z Day z Week z SemiMonth z Month z Year For SemiMonth, billing is done on the 1st and 15th of each month. NOTE: BILLINGFREQUENCY The combination of BillingPeriod and BillingFrequency cannot exceed one year.
PAGE 100
Recurring Payments and Reference Transactions API Operations CreateRecurringPaymentsProfile API Field Description TRIALBILLINGFREQUE NCY Number of billing periods that make up one billing cycle; required if you specify an optional trial period. The combination of billing frequency and billing period must be less than or equal to one year. For example, if the billing cycle is Month, the maximum value for billing frequency is 12.
PAGE 101
Recurring Payments and Reference Transactions API Operations CreateRecurringPaymentsProfile API Activation Details Type Field Description INITAMT (Optional) Initial non-recurring payment amount due immediately upon profile creation. Use an initial amount for enrolment or set-up fees. NOTE: All amounts included in the request must have the same currency. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol.
PAGE 102
Recurring Payments and Reference Transactions API Operations CreateRecurringPaymentsProfile API 102 Field Description SHIPTOCOUNTRYCODE Country code. This field is required if the shipping address is used. Character limit: 2 single-byte characters. SHIPTOPHONENUM (Optional) Phone number. Character length and limit: 20 single-byte characters.
PAGE 103
Recurring Payments and Reference Transactions API Operations CreateRecurringPaymentsProfile API Credit Card Details Fields Field Description CREDITCARDTYPE (Required) Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. Allowable values: z Visa z MasterCard z Discover z Amex z Maestro: See note. z Solo: See note. For Canada, only MasterCard and Visa are allowable; Interac debit cards are not supported.
PAGE 104
Recurring Payments and Reference Transactions API Operations CreateRecurringPaymentsProfile API Field Description PAYERSTATUS Status of payer. Valid values are: z verified z unverified Character length and limitations: 10 single-byte alphabetic characters. 104 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. BUSINESS Payer’s business name.
PAGE 105
Recurring Payments and Reference Transactions API Operations CreateRecurringPaymentsProfile API Payer Name Fields Field Description SALUTATION Payer’s salutation. Character length and limitations: 20 single-byte characters. FIRSTNAME Payer’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.
PAGE 106
Recurring Payments and Reference Transactions API Operations GetRecurringPaymentsProfileDetails API Field Description STATUS Status of the recurring payment profile. z ActiveProfile - The recurring payment profile has been successfully created and activated for scheduled payments according the billing instructions from the recurring payments profile. z PendingProfile - The system is in the process of creating the recurring payment profile. Please check your IPN messages for an update.
PAGE 107
Recurring Payments and Reference Transactions API Operations GetRecurringPaymentsProfileDetails API GetRecurringPaymentsProfileDetails Response Fields Field Description PROFILEID Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. STATUS Status of the recurring payment profile. z ActiveProfile z PendingProfile z CancelledProfile z SuspendedProfile z ExpiredProfile DESC Description of the recurring payment.
PAGE 108
Recurring Payments and Reference Transactions API Operations GetRecurringPaymentsProfileDetails API 108 Field Description PROFILEREFERENCE The merchant’s own unique reference or invoice number. Character length and limitations: 127 single-byte alphanumeric characters.
PAGE 109
Recurring Payments and Reference Transactions API Operations GetRecurringPaymentsProfileDetails API Ship To Address Type Fields Field Description ADDRESSSTATUS Status of street address on file with PayPal. Valid values are: z none z Confirmed z Unconfirmed 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.
PAGE 110
Recurring Payments and Reference Transactions API Operations GetRecurringPaymentsProfileDetails API Field Description BILLINGFREQUENCY Number of billing periods that make up one billing cycle. The combination of billing frequency and billing period must be less than or equal to one year. For example, if the billing cycle is Month, the maximum value for billing frequency is 12. Similarly, if the billing cycle is Week, the maximum value for billing frequency is 52.
PAGE 111
Recurring Payments and Reference Transactions API Operations GetRecurringPaymentsProfileDetails API Recurring Payments Summary Details Fields Field Description NEXTBILLINGDATE The next scheduled billing date, in YYYY-MM-DD format. NUMCYCYLESCOMPLETED The number of billing cycles completed in the current active subscription period. A billing cycle is considered completed when payment is collected or after retry attempts to collect payment for the current billing cycle have failed.
PAGE 112
Recurring Payments and Reference Transactions API Operations GetRecurringPaymentsProfileDetails API 112 Field Description EXPDATE Credit card expiration date. This field is required if you are using recurring payments with direct payments. Format: MMYYYY Character length and limitations: Six single-byte alphanumeric characters, including leading zero. STARTDATE Month and year that Maestro or Solo card was issued, the MMYYYY format. Character length: Must be six digits, including leading zero.
PAGE 113
Recurring Payments and Reference Transactions API Operations ManageRecurringPaymentsProfileStatus API Payer Info Type Fields Field Description Email address of payer. Character length and limitations: 127 single-byte characters. 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. Address Fields Field Description STREET First street address.
PAGE 114
Recurring Payments and Reference Transactions API Operations BillOutstandingAmount API ManageRecurringPaymentsProfileStatus Request ManageRecurringPaymentsProfileStatus Request Fields Field Description METHOD (Required) Must be ManageRecurringPaymentsProfileStatus. PROFILEID (Required) Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. Character length and limitations: 14 single-byte alphanumeric characters.
PAGE 115
Recurring Payments and Reference Transactions API Operations UpdateRecurringPaymentsProfile API BillOutstandingAmount Request BillOutstandingAmount Request Fields Field Description METHOD (Required) Must be BillOutstandingAmount. PROFILEID (Required) Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. Character length and limitations: 14 single-byte alphanumeric characters.
PAGE 116
Recurring Payments and Reference Transactions API Operations UpdateRecurringPaymentsProfile API UpdateRecurringPaymentsProfile Request 116 z UpdateRecurringPaymentsProfile Request Fields z Ship To Address Fields z Credit Card Fields z Payer Information Fields z Address Fields 08 April 2009 Name-Value Pair API Developer Guide
PAGE 117
Recurring Payments and Reference Transactions API Operations UpdateRecurringPaymentsProfile API UpdateRecurringPaymentsProfile Request Fields Field Description METHOD (Required) Must be UpdateRecurringPaymentsProfile. PROFILEID (Required) Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. Character length and limitations: 14 single-byte alphanumeric characters. 19 character profile IDs are supported for compatability with previous versions of the PayPal API.
PAGE 118
Recurring Payments and Reference Transactions API Operations UpdateRecurringPaymentsProfile API Field Description TAXAMT (Optional) Tax amount for each billing cycle during the regular payment period. NOTE: All amounts in the request must have the same currency. 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 (,).
PAGE 119
Recurring Payments and Reference Transactions API Operations UpdateRecurringPaymentsProfile API Ship To Address Fields Field Description SHIPTONAME Person’s name associated with this address. This field is required for shipping addresses but is optional for credit card billing addresses. Character length and limitations: 32 single-byte characters. SHIPTOSTREET First street address. This field is required if the shipping address is used. Character length and limitations: 100 single-byte characters.
PAGE 120
Recurring Payments and Reference Transactions API Operations UpdateRecurringPaymentsProfile API Field Description TOTALBILLINGCYCLES (Optional) The number of billing cycles for payment period. z For the regular payment period, if no value is specified or the value is 0, the regular payment period continues until the profile is canceled or deactivated.
PAGE 121
Recurring Payments and Reference Transactions API Operations UpdateRecurringPaymentsProfile API Field Description TRIALAMT Billing amount for each billing cycle during this payment period; required if you specify an optional trial period. This amount does not include shipping and tax amounts. NOTE: All amounts in the CreateRecurringPaymentsProfile request must have the same currency. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol.
PAGE 122
Recurring Payments and Reference Transactions API Operations UpdateRecurringPaymentsProfile API Credit Card Details Fields Field Description CREDITCARDTYPE (Required) Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. Allowable values: z Visa z MasterCard z Discover z Amex z Maestro: See note. z Solo: See note. For Canada, only MasterCard and Visa are allowable; Interac debit cards are not supported.
PAGE 123
Recurring Payments and Reference Transactions API Operations SetCustomerBillingAgreement API Field Description LASTNAME (Required) Payer’s last name. Character length and limitations: 25 single-byte characters. Address Fields Field Description STREET (Required) First street address. Character length and limitations: 100 single-byte characters. STREET2 (Optional) Second street address. Character length and limitations: 100 single-byte characters. CITY (Required) Name of city.
PAGE 124
Recurring Payments and Reference Transactions API Operations SetCustomerBillingAgreement API z “SetCustomerBillingAgreement Response” on page 127 SetCustomerBillingAgreement Request 124 z SetCustomerBillingAgreement Request Fields z “Billing Agreement Details Fields” on page 127 08 April 2009 Name-Value Pair API Developer Guide
PAGE 125
Recurring Payments and Reference Transactions API Operations SetCustomerBillingAgreement API SetCustomerBillingAgreement Request Fields Field Description METHOD (Required) Must be SetCustomerBillingAgreement. RETURNURL (Required) URL to which the customer’s browser is returned after choosing to pay with PayPal. NOTE: PayPal recommends that the value be the final review page on which the customer confirms the billing agreement. Character length and limitations: no limit.
PAGE 126
Recurring Payments and Reference Transactions API Operations SetCustomerBillingAgreement API 126 Field Description HDRBACKCOLOR (Optional) Sets the background color for the header of the payment page. By default, the color is white. Character length and limitation: Six character HTML hexadecimal color code in ASCII. PAYFLOWCOLOR (Optional) Sets the background color for the payment page. Character length and limitation: Six character HTML hexadecimal color code in ASCII.
PAGE 127
Recurring Payments and Reference Transactions API Operations GetBillingAgreementCustomerDetails API Billing Agreement Details Fields Field Description L_BILLINGTYPEn (Required) Type of billing agreement. For recurring payments, this field must be set to RecurringPayments. In this case, you can specify up to ten billing agreements. NOTE: Other defined values are not valid.
PAGE 128
Recurring Payments and Reference Transactions API Operations GetBillingAgreementCustomerDetails API GetBillingAgreementCustomerDetails Request GetBillingAgreementCustomerDetails Request Fields Field Description METHOD (Required) Must be GetBillingAgreementCustomerDetails. TOKEN (Required) The time-stamped token returned in the SetCustomerBillingAgreement response. NOTE: The token expires after three hours. Character length and limitations: 20 single-byte characters.
PAGE 129
Recurring Payments and Reference Transactions API Operations GetBillingAgreementCustomerDetails API GetBillingAgreementCustomerDetails Response Fields Payer Information Fields Field Description 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.
PAGE 130
Recurring Payments and Reference Transactions API Operations BAUpdate API Field Description 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. SHIPTOSTREET2 Second street address. Character length and limitations: 100 single-byte characters. SHIPTOCITY Name of city. Character length and limitations: 40 single-byte characters.
PAGE 131
Recurring Payments and Reference Transactions API Operations BAUpdate API BAUpdate Request Update Billing Agreement Request Fields Field Description METHOD (Required) Must be BillAgreementUpdate. REFERENCEID (Required) An ID, such as a billing agreement ID or a reference transaction ID that is associated with a billing agreement. BILLINGAGREEMENTSTA TUS (Optional) Type of billing agreement.
PAGE 132
Recurring Payments and Reference Transactions API Operations BAUpdate API Update Billing Agreement Details Response Fields Field Description L_BILLINGTYPEn Type of billing agreement. L_BILLINGAGREEMENTD ESCRIPTIONn Description of goods or services associated with the billing agreement, which is required for each recurring payment billing agreement. Character length and limitations: 127 single-byte alphanumeric bytes. L_CUSTOMn Custom annotation field for your own use.
PAGE 133
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API Field Description FIRSTNAME Payer’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.
PAGE 134
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API z “DoReferenceTransaction Response” on page 143 DoReferenceTransaction Request 134 z DoReferenceTransaction Request Fields z Ship To Address Fields z Payment Details Type Fields z Payment Details Item Type Fields z eBay Item Payment Details Item Type Fields z Credit Card Fields z Payer Information Fields z Billing Address Fields 08 April 2009 Name-Value Pair API Developer Guide
PAGE 135
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API DoReferenceTransaction Request Fields Field Description METHOD (Required) Must be DoReferenceTransaction. REFERENCEID (Required) A transaction ID from a previous purchase, such as a credit card charge using the DoDirectPayment API, or a billing agreement ID.
PAGE 136
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API Ship To Address Fields Field Description SHIPTONAME Person’s name associated with this address. This field is required for shipping addresses but is optional for credit card billing addresses. Character length and limitations: 32 single-byte characters. SHIPTOSTREET First street address. This field is required if the shipping address is used. Character length and limitations: 100 single-byte characters.
PAGE 137
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API Field Description SHIPPINGAMT (Optional) Total shipping costs for this order. INSURANCEAMT 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.
PAGE 138
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API Field Description INVNUM (Optional) Your own invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters BUTTONSOURCE (Optional) An identification code for use by third-party applications to identify transactions.
PAGE 139
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API Payment Details Item Type Fields Field Description L_NAMEn (Optional) Item name. These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1). Character length and limitations: 127 single-byte characters L_DESCn (Optional) Item description. Character length and limitations: 127 single-byte characters L_AMTn (Optional) Cost of item.
PAGE 140
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API 140 Field Description L_ITEMWIDTHVALUEn, L_ITEMWIDTHUNITn (Optional) Item width corresponds to the width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query. These parameters must be ordered sequentially beginning with 0 (for example L_ITEMWIDTHVALUE0, L_ITEMWIDTHVALUE1).
PAGE 141
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API EbayItemPaymentDetailsItemType Fields Field Description L_EBAYITEMNUMBERn (Optional) Auction item number. These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1). Character length: 765 single-byte characters L_EBAYITEMAUCTIONTX NIDn (Optional) Auction transaction identification number.
PAGE 142
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API 142 Field Description CVV2 Card Verification Value, version 2. Your Merchant Account settings determine whether this field is required. Character length for Visa, MasterCard, and Discover: exactly three digits.Character length for American Express: exactly four digits.To comply with credit card processing regulations, you must not store this value after a transaction has been completed.
PAGE 143
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API Payer Info Type Fields Field Description EMAIL (Optional) Email address of payer. Character length and limitations: 127 single-byte characters. FIRSTNAME (Required) Payer’s first name. Character length and limitations: 25 single-byte characters. LASTNAME (Required) Payer’s last name. Character length and limitations: 25 single-byte characters.
PAGE 144
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API DoReferenceTransaction Response Fields for Express Checkout Field Description AVSCODE Address Verification System response code. See “AVS and CVV2 Response Codes” on page 241 for possible values. Character limit: One single-byte alphanumeric character CVV2MATCH Result of the CVV2 check by PayPal. BILLINGAGREEMENTID Returned if the value of ReferenceID in the request is a billing agreement identification number.
PAGE 145
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API Field Description PAYMENTTYPE Indicates whether the payment is instant or delayed. Character length and limitations: Seven single-byte characters Valid values: z none z echeck z instant ORDERTIME Time/date stamp of payment AMT The final amount charged, including any shipping and taxes from your Merchant Profile. Character length and limitations: Does not exceed $10,000 USD in any currency. No currency symbol.
PAGE 146
Recurring Payments and Reference Transactions API Operations DoReferenceTransaction API 146 Field Description PENDINGREASON The reason the payment is pending: z none: No pending reason. z 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.
PAGE 147
10 DoNonReferencedCredit API Issue a credit to a card not referenced by the original transaction.
PAGE 148
DoNonReferencedCredit API DoNonReferencedCredit Request DoNonReferencedCredit Request Fields 148 Field Description METHOD (Required) Must be DoNonReferencedCredit. AMT (Required) Total of order, including shipping, handling, and tax. 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 (,).
PAGE 149
DoNonReferencedCredit API DoNonReferencedCredit Request Credit Card Details Fields Field Description CREDITCARDTYPE (Required) Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. Allowable values: z Visa z MasterCard z Discover z Amex z Maestro: See note. z Solo: See note. For Canada, only MasterCard and Visa are allowable; Interac debit cards are not supported. NOTE: If the credit card type is Maestro or Solo, the CURRENCYCODE must be GBP.
PAGE 150
DoNonReferencedCredit API DoNonReferencedCredit Response Field Description LASTNAME (Required) Payer’s last name. Character length and limitations: 25 single-byte characters. Address Fields Field Description STREET (Required) First street address. Character length and limitations: 100 single-byte characters. STREET2 (Optional) Second street address. Character length and limitations: 100 single-byte characters. CITY (Required) Name of city.
PAGE 151
11 ManagePendingTransactionStatu s API Accept or deny a pending transaction held by Fraud Management Filters. z “ManagePendingTransactionStatus Request” on page 151 z “ManagePendingTransactionStatus Response” on page 151 ManagePendingTransactionStatus Request ManagePendingTransactionStatus Request Fields Field Description METHOD (Required) Must be ManagePendingTransactionStatus. TRANSACTIONID (Required) The transaction ID of the payment transaction.
PAGE 152
ManagePendingTransactionStatus API ManagePendingTransactionStatus Response 152 08 April 2009 Name-Value Pair API Developer Guide
PAGE 153
12 GetBalance API Obtain the available balance for a PayPal account. z “GetBalance Request” on page 153 z “GetBalance Response” on page 153 GetBalance Request GetBalance Request Fields Field Description METHOD (Required) Must be GetBalance.
PAGE 154
GetBalance API GetBalance Response 154 08 April 2009 Name-Value Pair API Developer Guide
PAGE 155
13 AddressVerify API Confirms whether a postal address and postal code match those of the specified PayPal account holder.
PAGE 156
AddressVerify API AddressVerify Request AddressVerify Request AddressVerify Request Fields Field Description METHOD (Required) Must be AddressVerify. EMAIL (Required) Email address of a PayPal member to verify. Maximum string length: 255 single-byte characters Input mask: ?@?.?? STREET (Required) First line of the billing or shipping postal address to verify. To pass verification, the value of Street must match the first three single-byte characters of a postal address on file for the PayPal member.
PAGE 157
AddressVerify API AddressVerify Response Field Description ZIPMATCH None: The request value of the Street element was unmatched. No comparison of the Zip element was made. Matched: The request value of the Zip element matches the ZIP code of the postal address on file for the PayPal member. Unmatched: The request value of the Zip element does not match the ZIP code of the postal address on file for the PayPal member.
PAGE 158
AddressVerify API AddressVerify Response 158 08 April 2009 Name-Value Pair API Developer Guide
PAGE 159
A API Error Codes The PayPal API can return multiple errors for any operation.
PAGE 160
API Error Codes General API Errors General API Errors General API Errors Error Code 160 Short Message Long Message Correcting This Error 10002 Authentication/Authoriza tion Failed Username/Password is incorrect 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.
PAGE 161
API Error Codes Validation Errors Validation Errors 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 811
PAGE 162
API Error Codes Validation Errors 162 Error Code Short Message Long Message 81122 Missing Parameter TaxAmt : Required parameter missing 81123 Missing Parameter IPAddress : Required parameter missing 81124 Missing Parameter ShipToName : Required parameter missing 81125 Missing Parameter L_Amt : Required parameter missing 81126 Missing Parameter Amt : Required parameter missing 81127 Missing Parameter L_TaxAmt : Required parameter missing 81128 Missing Parameter AuthorizationID : Requ
PAGE 163
API Error Codes Validation Errors Error Code Short Message Long Message 81203 Invalid Parameter NotifyURL : Invalid parameter 81205 Invalid Parameter ShipToStreet : Invalid parameter 81206 Invalid Parameter ShipToStreet2 : Invalid parameter 81207 Invalid Parameter ShipToCity : Invalid parameter 81208 Invalid Parameter ShipToState : Invalid parameter 81209 Invalid Parameter ShipToZip : Invalid parameter 81210 Invalid Parameter Country : Invalid parameter 81211 Invalid Parameter Req
PAGE 164
API Error Codes Validation Errors 164 Error Code Short Message Long Message 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 08 April 2009 Name-Value Pair API Develope
PAGE 165
API Error Codes Direct Payment API Errors Direct Payment API Errors DirectPayment API Errors Error Code Short Message Long Message 10102 PaymentAction of Order Temporarily Unavailable PaymentAction of Order is temporarily unavailable. Please try later or use other PaymentAction. 10401 Transaction refused Order total is missing. because of an invalid argument. See additional error messages for details. 10418 The currencies of the shopping Transaction refused cart amounts must be the same.
PAGE 166
API Error Codes Direct Payment API Errors 166 Error Code Short Message Long Message Corrective Action 10502 Invalid Data This transaction cannot be processed. Please use a valid credit card. The credit card used is expired. 10504 Invalid Data This transaction cannot be processed. Please enter a valid Credit Card Verification Number. The CVV provided is invalid. The CVV is between 3-4 digits long. 10505 Gateway Decline This transaction cannot be processed.
PAGE 167
API Error Codes Direct Payment API Errors Error Code Short Message Long Message Corrective Action 10525 Invalid Data This transaction cannot be processed. The amount to be charged is zero. The merchant entered a amount of zero. 10526 Invalid Data This transaction cannot be processed. The currency is not supported at this time. The currency code entered is not supported. 10527 Invalid Data This transaction cannot be processed. Please enter a valid credit card number and type.
PAGE 168
API Error Codes Direct Payment API Errors 168 Error Code Short Message Long Message Corrective Action 10544 Gateway Decline This transaction cannot be processed. The transaction was declined by PayPal. Contact PayPal for more information. 10545 Gateway Decline This transaction cannot be processed. The transaction was declined by PayPal because of possible fraudulent activity. Contact PayPal for more information. 10546 Gateway Decline This transaction cannot be processed.
PAGE 169
API Error Codes Direct Payment API Errors Error Code Short Message Long Message Corrective Action 10556 Filter Decline This transaction cannot be processed. The transaction was declined because of a merchant risk filter for AVS. Specifically, the merchant has set to decline transaction when the AVS was unsupported. 10561 Invalid Data There’s an error with this transaction. Please enter complete billing address. 10562 Invalid Data This transaction cannot be processed.
PAGE 170
API Error Codes Direct Payment API Errors 170 Error Code Short Message Long Message Corrective Action 10703 Invalid Data There’s an error with this transaction. Please enter a valid address2 in the billing address. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. 10704 Invalid Data There’s an error with this transaction. Please enter a valid city in the billing address.
PAGE 171
API Error Codes Direct Payment API Errors Error Code Short Message Long Message Corrective Action 10711 Invalid Data There’s an error with this transaction. Please enter your state in the billing address. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. 10712 Invalid Data There’s an error with this transaction. Please enter your five digit postal code in the billing address.
PAGE 172
API Error Codes Direct Payment API Errors 172 Error Code Short Message Long Message Corrective Action 10720 Invalid Data There’s an error with this transaction. Please enter a valid address1 in the shipping address. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. 10721 Invalid Data There’s an error with this transaction. Please enter a valid address2 in the shipping address.
PAGE 173
API Error Codes Direct Payment API Errors Error Code Short Message Long Message Corrective Action 10728 Invalid Data There’s an error with this transaction. Please enter a city in the shipping address. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. 10728 Invalid Data There’s an error with this transaction. Please enter a city in the shipping address. There was a problem with a particular field in the address.
PAGE 174
API Error Codes Direct Payment API Errors 174 Error Code Short Message Long Message Corrective Action 10736 Invalid Data There’s an error with this transaction. Please enter a valid city and state in the shipping address. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. 10744 Invalid Data This transaction cannot be processed. Please enter a valid country code in the billing address.
PAGE 175
API Error Codes Direct Payment API Errors Error Code Short Message Long Message Corrective Action 10756 Gateway Decline The transaction cannot be processed. The country and billing address associated with this credit card do not match. None - this is a PayPal internal error. 10758 Invalid Configuration There’s been an error due to invalid API username and/or password. The API username or password is incorrect for this merchant. 10759 Gateway Decline This transaction cannot be processed.
PAGE 176
API Error Codes Direct Payment API Errors 176 Error Code Short Message Long Message Corrective Action 15001 Gateway Decline This transaction cannot be processed. The transaction was rejected by PayPal because of excessive failures over a short period of time for this credit card. Contact PayPal for more information. 15002 Gateway Decline This transaction cannot be processed. The transaction was declined by PayPal. Contact PayPal for more information.
PAGE 177
API Error Codes SetExpressCheckout API Errors SetExpressCheckout API Errors SetExpressCheckout API Errors Error Code Short Message Long Message 10001 ButtonSource value truncated. The transaction could not be loaded 10001 Internal Error Internal Error 10004 Transaction refused because of an invalid argument. See additional error messages for details. Transaction refused because of an invalid argument. See additional error messages for details.
PAGE 178
API Error Codes SetExpressCheckout API Errors Error Code 178 Short Message Long Message 10404 Transaction refused because of an invalid argument. See additional error messages for details. ReturnURL is missing. 10405 Transaction refused because of an invalid argument. See additional error messages for details. CancelURL is missing. 10407 Transaction refused because of an invalid argument. See additional error messages for details. Invalid buyer email address (BuyerEmail).
PAGE 179
API Error Codes SetExpressCheckout API Errors Error Code 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.
PAGE 180
API Error Codes SetExpressCheckout API Errors Error Code 180 Short Message Long Message 10427 Transaction refused because of an invalid argument. See additional error messages for details Shipping total is invalid. 10428 Transaction refused because of an invalid argument. See additional error messages for details Handling total is invalid. 10429 Transaction refused because of an invalid argument. See additional error messages for details Tax total is invalid.
PAGE 181
API Error Codes SetExpressCheckout API Errors Error Code Short Message Long Message 10438 Transaction refused because of an invalid argument. See additional error messages for details. cpp-header-image value exceeds maximum allowable length. 10439 Transaction refused because of an invalid argument. See additional error messages for details. cpp-header-image value exceeds maximum allowable length. 10440 Transaction refused because of an invalid argument. See additional error messages for details.
PAGE 182
API Error Codes SetExpressCheckout API Errors Error Code 182 Short Message Long Message 10468 Transaction refused because of an invalid argument. See additional error messages for details Duplicate Order ID 10469 PaymentAction of Order Temporarily Unavailable Express Auctions is unavailable 10470 Wowo flag is off for ExpressO feature Solution Type passed as Sole while ExpressO feature is turned off 10471 Transaction refused because of an invalid argument.
PAGE 183
API Error Codes SetExpressCheckout API Errors Error Code Short Message Long Message 10537 Risk Control Country Filter Failure The transaction was refused because the country was prohibited as a result of your Country Monitor Risk Control Settings. 10538 Risk Control Max Amount Failure The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk Control Settings. 10539 Payment declined by your Risk Controls settings: PayPal Risk Model.
PAGE 184
API Error Codes SetExpressCheckout API Errors 184 Error Code Short Message Long Message 11803 Invalid Data You cannot pass both the new and deprecated Invoice ID parameter. 11804 Invalid Data You cannot pass both the new and deprecated order description. 11805 Invalid Data You cannot pass both the new and deprecated order total or amount parameters. 11806 Invalid Data You cannot pass both the new and deprecated ProfileAddressChangeDate parameter.
PAGE 185
API Error Codes SetExpressCheckout API Errors Error Code Short Message Long Message Invalid callback timeout The callback timeout is is zero; you must specify a longer timeout Line items missing Line items are required when specify a callback URL for flate rate shipping options Callback URL is too long The callback URL must not exceed 1,024 characters Multiple default shipping options specified You can only specify one default shipping option at a time No default shipping option specified You m
PAGE 186
API Error Codes SetExpressCheckout API Errors Error Code 186 Short Message Long Message 11828 Maximum amount of order not specified Maximum amount of order not specified; you must specify the estimated value of the order when using a flat-rate shipping option 11829 Shipping total is missing Shipping total is missing; you must specify a shipping total when using a flat-rate shipping option 11830 Insurance amount is missing Insurance amount is missing; you have offered insurance but have not spec
PAGE 187
API Error Codes GetExpressCheckoutDetails API Errors GetExpressCheckoutDetails API Errors GetExpressCheckoutDetails API Errors Error Code Short Message Long Message 10001 Internal Error Internal Error 10001 Internal Error Transaction failed due to internal error 10001 ButtonSource value truncated. The transaction could not be loaded 10001 ButtonSource value truncated. The transaction could not be loaded 10004 Transaction refused because of an invalid argument.
PAGE 188
API Error Codes GetExpressCheckoutDetails API Errors Error Code 10411 188 Short Message Long Message This Express Checkout session has expired. This Express Checkout session has expired. Token value is no longer valid. 08 April 2009 Correcting This Error...
PAGE 189
API Error Codes DoExpressCheckoutPayment API Errors DoExpressCheckoutPayment API Errors Errors Error Code Short Message Long Message 10001 Internal Error Transaction failed due to internal error 10001 Internal Error Warning an internal error has occurred. The transaction id may not be correct 10001 ButtonSource value truncated. The transaction could not be loaded 10001 Internal Error Internal Error 10004 Transaction refused because of an invalid argument.
PAGE 190
API Error Codes DoExpressCheckoutPayment API Errors Error Code 10413 Short Message Long Message 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. Correcting This Error... z z z z ItemTotal ShippingTotal HandlingTotal 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.
PAGE 191
API Error Codes DoExpressCheckoutPayment API Errors Error Code Short Message Long Message 10422 Customer must choose new funding sources. The customer must return to PayPal to select new funding sources. 10424 Transaction refused because of an invalid argument. See additional error messages for details. Shipping address is invalid. 10426 Transaction refused because of an invalid argument. See additional error messages for details. Item total is invalid.
PAGE 192
API Error Codes DoExpressCheckoutPayment API Errors Error Code 192 Short Message Long Message 10435 Transaction refused because of an invalid argument. See additional error messages for details. The customer has not yet confirmed payment for this Express Checkout session. 10441 Transaction refused because of an invalid argument. See additional error messages for details. The NotifyURL element value exceeds maximum allowable length. 10442 ButtonSource value truncated.
PAGE 193
API Error Codes DoExpressCheckoutPayment API Errors Error Code Short Message Long Message 10538 Risk Control Max Amount Failure The transaction was refused because the maximum amount was excceeded as a result of your Maximum Amount Risk Control Settings. 10539 Payment declined by your Risk Controls settings: PayPal Risk Model. Payment declined by your Risk Controls settings: PayPal Risk Model.
PAGE 194
API Error Codes DoExpressCheckoutPayment API Errors Error Code 194 Short Message Long Message Invalid shipping options Invalid shipping options; you must specify a name and amount for each shipping option 11821 Invalid shipping options Invalid shipping options; you must specify a name and amount for each shipping option type 11826 Invalid shipping total Invalid shipping total; it should equal the shipping amount of the selected shipping option 08 April 2009 Correcting This Error...
PAGE 195
API Error Codes Authorization and Capture API Errors Authorization and Capture API Errors Authorization & Capture API Error Messages Error Code Short Message Long Message 10001 Internal Error Internal Error 10001 Internal Error Transaction failed due to internal error 10004 Internal Error Invalid argument 10007 Permission denied You do not have permissions to make this API call 10009 Transaction refused Account is locked or inactive 10010 Transaction refused because of an invalid argumen
PAGE 196
API Error Codes Authorization and Capture API Errors 196 Error Code Short Message Returned By API Call... Correcting This Error... 10604 Authorization must include both buyer and seller. Authorization transaction cannot be unilateral. It must include both buyer and seller to make an auth. DoAuthorization Review the order to ensure customer and seller are both PayPal members. 10605 Unsupported currency. Currency is not supported.
PAGE 197
API Error Codes Authorization and Capture API Errors Error Code Short Message Returned By API Call... Correcting This Error... 10615 Cannot reauth reauth. You can reauthorize only the original authorization, not a reauthorization. DoReauthorization Capture the reauthorization. 10616 Maximum number of reauthorization allowed for the auth is reached. Maximum number of reauthorization allowed for the auth is reached.
PAGE 198
API Error Codes Authorization and Capture API Errors 198 Error Code Short Message Long Message Returned By API Call... Correcting This Error... 10625 Transaction refused because of an invalid argument. See additional error messages for details. The amount exceeds the maximum amount for a single transaction. DoAuthorization DoCapture DoReauthorization Reattempt the request with a lower amount. 10626 Risk Transaction refused due to risk model.
PAGE 199
API Error Codes GetTransactionDetails API Errors GetTransactionDetails API Errors GetTransactionDetails API Errors Error Code Short Message Long Message 10001 Internal Error Internal Error TransactionSearch API Errors TransactionSearch API Errors Error Code Short Message Long Message 10001 Internal Error Internal Error 10001 ButtonSource value truncated. The transaction could not be loaded 10003 Transaction refused because of an invalid argument. See additional error messages for details.
PAGE 200
API Error Codes TransactionSearch API Errors Error Code 200 Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. Payer email is invalid 10004 Transaction refused because of an invalid argument. See additional error messages for details. Auction item id is not valid 10004 Transaction refused because of an invalid argument. See additional error messages for details.
PAGE 201
API Error Codes RefundTransaction API Errors RefundTransaction API Errors RefundTransaction API Errors 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. See additional error messages for details.
PAGE 202
API Error Codes RefundTransaction API Errors Error Code 202 Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details.
PAGE 203
API Error Codes RefundTransaction API Errors Error Code Short Message Long Message 10009 Transaction refused This transaction has already been fully refunded 10009 Transaction refused Account is restricted 10009 Transaction refused You can not refund this type of transaction 10009 Transaction refused You can not do a partial refund on this transaction 10009 Transaction refused The account for the counterparty is locked or inactive 10009 Transaction refused You can not refund this type o
PAGE 204
API Error Codes Mass Pay API Errors Mass Pay API Errors MassPay API Errors 204 Error Code Short Message Long Message 10001 Invalid account number. The transaction failed as a result of an invalid credit card 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 value truncated. The transaction could not be loaded 10001 Transaction refused because of an invalid argument.
PAGE 205
API Error Codes Mass Pay API Errors Error Code Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. The amount is not a valid number 10004 Transaction refused because of an invalid argument. See additional error messages for details. The amount exceeds the max limit of a single mass pay item ~1 10004 Transaction refused because of an invalid argument. See additional error messages for details.
PAGE 206
API Error Codes Recurring Payments Errors Error Code Short Message Long Message 10311 Unable to submit payment Unable to submit payments for masspay 10312 Masspay server error The masspay server has reported errors 10313 Masspay Invalid Data The masspay input file includes invalid data 10314 Masspay input parse error The input to the masspay server is incorrect. Please make sure that you are using a correctly formatted input.
PAGE 207
API Error Codes Recurring Payments Errors Recurring Payments Errors Error Code Short Message Long Message 10001 Invalid account number The transaction failed as a result of invalid credit card number. Check the number or attempt with another credit card. 10478 Invalid Data Recurring payments profile description must be provided if the billing agreement type is recurring payments. 10501 Invalid Configuration This transaction cannot be processed due to an invalid merchant configuration.
PAGE 208
API Error Codes Recurring Payments Errors 208 Error Code Short Message Long Message Additional Information 10513 Invalid Data This transaction cannot be processed. Please enter a last name. The last name of the buyer is required for this merchant. 10535 Gateway decline This transaction cannot be processed. Please enter a valid credit card number and type. 10548 Invalid Configuration This transaction cannot be processed. The merchant’s account is not able to process transactions.
PAGE 209
API Error Codes Recurring Payments Errors Error Code Short Message Long Message Additional Information 10744 Invalid Data This transaction cannot be processed. Please enter a valid country code in the billing address. There was a problem with a particular field in the address. The long error message will tell you what field is invalid. 10748 Invalid Data This transaction cannot be processed without a Credit Card Verification Number.
PAGE 210
API Error Codes Recurring Payments Errors Error Code 210 Short Message Long Message 11508 Invalid trial total billing cycles Trial total billing cycles must be > 0 11509 Invalid trial billing period Trial billing period must be one of Day, Week, Month, SemiMonth, or Year 11510 Invalid trial amount Trial amount must be >= 0 11511 Invalid currency for trial amount This currency is currently not supported for trial amount. Currency must be USD.
PAGE 211
API Error Codes Recurring Payments Errors Error Code Short Message Long Message 11544 Invalid period status The trial period status must be one of (A)ctive or (C)ancelled 11545 Denied Payer’s account is denied 11546 Denied Merchant account is denied 11547 This feature is not available at this time Recurring payments feature is not currently available; try again later 11548 Invalid currency code Invalid currency code, all currency codes much match 11549 Start Date is required Subscriptio
PAGE 212
API Error Codes Recurring Payments Errors Error Code 212 Short Message Long Message 11567 The time of the update is too close to the billing date The time of the update is too close to the billing date 11568 Invalid currency for delinquent amount Invalid currency for delinquent amount 11569 Cannot increase delinquent amount Cannot increase delinquent amount 11570 The maximum number of failed payments should be greater than the current number of failed payments The maximum number of failed pa
PAGE 213
API Error Codes SetCustomerBillingAgreement Errors SetCustomerBillingAgreement Errors SetCustomerBillingAgreement Errors Error Code Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. Invalid argument; BillingType input field is set to None 10404 Transaction refused because of an invalid argument. See additional error messages for details. ReturnURL is missing. 10004 Transaction refused because of an invalid argument.
PAGE 214
API Error Codes SetCustomerBillingAgreement Errors Error Code 214 Short Message Long Message Additional Information 10440 Transaction refused because of an invalid argument. See additional error messages for details. cpp-payflow-color value exceeds maximum allowable length. cpp_payflow_color tag is too long; maximum length is 6 10471 Transaction refused because of an invalid argument. See additional error messages for details. ReturnURL is invalid.
PAGE 215
API Error Codes GetBillingAgreementCustomerDetails Errors GetBillingAgreementCustomerDetails Errors GetBillingAgreementCustomerDetails Errors Error Code Short Message Long Message Additional Information 10408 Missing token Token is missing Token is missing 10409 You’re not authorized to access this info. Express Checkout token was issued for a merchant account other than yours.
PAGE 216
API Error Codes CreateBillingAgreement Errors Error Code 10411 216 Short Message Long Message Additional Information This Express Checkout session has expired. This Express Checkout session has expired. Token value is no longer valid.
PAGE 217
API Error Codes UpdateBillingAgreement Errors UpdateBillingAgreement Errors UpdateBillingAgreement Errors Error Code Short Message Long Message 10001 Internal Error Internal Error 10004 Transaction refused because of an invalid argument. See additional error messages for details. Invalid argument; description field or custom field is empty and the status is active Check the description and custom fields of the billing agreement.
PAGE 218
API Error Codes DoReferenceTransaction Errors Error Code Short Message Long Message 10002 Authentication/Authorizati on Failed 10004 Transaction refused because of an invalid argument. See additional error messages for details.
PAGE 219
API Error Codes DoReferenceTransaction Errors Error Code Short Message Long Message 10216 Additional Information Transaction refused because a confirmed address is not available 10400 Transaction refused because of an invalid argument. See additional error messages for details. Order total is missing. TotalOrder amount is missing 10401 Transaction refused because of an invalid argument. See additional error messages for details. Order total is invalid.
PAGE 220
API Error Codes DoReferenceTransaction Errors Error Code 220 Short Message Long Message Additional Information 10420 Transaction refused because of an invalid argument. See additional error messages for details. PaymentAction? tag is missing. PaymentAction? tag is missing. 10426 Transaction refused because of an invalid argument. See additional error messages for details. Item total is invalid. ItemTotal amount is invalid. 10427 Transaction refused because of an invalid argument.
PAGE 221
API Error Codes DoReferenceTransaction Errors Error Code Short Message Long Message Additional Information 10434 Transaction refused because of an invalid argument. See additional error messages for details. Value of Custom element has been truncated. Custom field is too long; maximum length is 256. Warning only; API executes 10441 Transaction refused because of an invalid argument. See additional error messages for details. The NotifyURL element value exceeds maximum allowable length.
PAGE 222
API Error Codes DoReferenceTransaction Errors 222 Error Code Short Message Long Message 10622 Order is voided. Order is voided. 10623 Maximum number of authorization allowed for the order is reached. Maximum number of authorization allowed for the order is reached.
PAGE 223
API Error Codes DoReferenceTransaction Errors Error Code Short Message Long Message Additional Information 11451 Billing Agreement Id or transaction Id is not valid Billing Agreement Id or transaction Id is not valid Reference id either not found or could not be decrypted 11452 Merchant not enabled for reference transactions Merchant not enabled for reference transactions This merchant is not enabled for Mark reference transaction 11453 Reference transactions temporarily unavailable.
PAGE 224
API Error Codes AddressVerify API Errors AddressVerify API Errors AddressVerify API Errors Error Code Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. Invalid email format 10004 Transaction refused because of an invalid argument. See additional error messages for details. Invalid street format 10004 Transaction refused because of an invalid argument. See additional error messages for details.
PAGE 225
B Country Codes Country Codes Country Code AFGHANISTAN AF ÅLAND ISLANDS AX ALBANIA AL ALGERIA DZ AMERICAN SAMOA AS ANDORRA AD ANGOLA AO ANGUILLA AI ANTARCTICA AQ ANTIGUA AND BARBUDA AG ARGENTINA AR ARMENIA AM ARUBA AW AUSTRALIA AU AUSTRIA AT AZERBAIJAN AZ BAHAMAS BS BAHRAIN BH BANGLADESH BD BARBADOS BB BELARUS BY BELGIUM BE BELIZE BZ BENIN BJ BERMUDA BM Name-Value Pair API Developer Guide 08 April 2009 225
PAGE 226
Country Codes 226 Country Code BHUTAN BT BOLIVIA BO BOSNIA AND HERZEGOVINA BA BOTSWANA BW BOUVET ISLAND BV BRAZIL BR BRITISH INDIAN OCEAN TERRITORY IO BRUNEI DARUSSALAM BN BULGARIA BG BURKINA FASO BF BURUNDI BI CAMBODIA KH CAMEROON CM CANADA CA CAPE VERDE CV CAYMAN ISLANDS KY CENTRAL AFRICAN REPUBLIC CF CHAD TD CHILE CL CHINA CN CHRISTMAS ISLAND CX COCOS (KEELING) ISLANDS CC COLOMBIA CO COMOROS KM CONGO CG CONGO, THE DEMOCRATIC REPUBLIC OF THE CD COOK
PAGE 227
Country Codes Country Code CROATIA HR CUBA CU CYPRUS CY CZECH REPUBLIC CZ DENMARK DK DJIBOUTI DJ DOMINICA DM DOMINICAN REPUBLIC DO ECUADOR EC EGYPT EG EL SALVADOR SV EQUATORIAL GUINEA GQ ERITREA ER ESTONIA EE ETHIOPIA ET FALKLAND ISLANDS (MALVINAS) FK FAROE ISLANDS FO FIJI FJ FINLAND FI FRANCE FR FRENCH GUIANA GF FRENCH POLYNESIA PF FRENCH SOUTHERN TERRITORIES TF GABON GA GAMBIA GM GEORGIA GE GERMANY DE GHANA GH GIBRALTAR GI Name-Value Pair API De
PAGE 228
Country Codes 228 Country Code GREECE GR GREENLAND GL GRENADA GD GUADELOUPE GP GUAM GU GUATEMALA GT GUERNSEY GG GUINEA GN GUINEA-BISSAU GW GUYANA GY HAITI HT HEARD ISLAND AND MCDONALD ISLANDS HM HOLY SEE (VATICAN CITY STATE) VA HONDURAS HN HONG KONG HK HUNGARY HU ICELAND IS INDIA IN INDONESIA ID IRAN, ISLAMIC REPUBLIC OF IR IRAQ IQ IRELAND IE ISLE OF MAN IM ISRAEL IL ITALY IT JAMAICA JM JAPAN JP JERSEY JE JORDAN JO 08 April 2009 Name-Value Pair
PAGE 229
Country Codes Country Code KAZAKHSTAN KZ KENYA KE KIRIBATI KI KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF KP KOREA, REPUBLIC OF KR KUWAIT KW KYRGYZSTAN KG LAO PEOPLE'S DEMOCRATIC REPUBLIC LA LATVIA LV LEBANON LB LESOTHO LS LIBERIA LR LIBYAN ARAB JAMAHIRIYA LY LIECHTENSTEIN LI LITHUANIA LT LUXEMBOURG LU MACAO MO MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF MK MADAGASCAR MG MALAWI MW MALAYSIA MY MALDIVES MV MALI ML MALTA MT MARSHALL ISLANDS MH MARTINIQUE MQ MAUR
PAGE 230
Country Codes 230 Country Code MEXICO MX MICRONESIA, FEDERATED STATES OF FM MOLDOVA, REPUBLIC OF MD MONACO MC MONGOLIA MN MONTSERRAT MS MOROCCO MA MOZAMBIQUE MZ MYANMAR MM NAMIBIA NA NAURU NR NEPAL NP NETHERLANDS NL NETHERLANDS ANTILLES AN NEW CALEDONIA NC NEW ZEALAND NZ NICARAGUA NI NIGER NE NIGERIA NG NIUE NU NORFOLK ISLAND NF NORTHERN MARIANA ISLANDS MP NORWAY NO OMAN OM PAKISTAN PK PALAU PW PALESTINIAN TERRITORY, OCCUPIED PS PANAMA PA PAPUA NEW
PAGE 231
Country Codes Country Code PARAGUAY PY PERU PE PHILIPPINES PH PITCAIRN PN POLAND PL PORTUGAL PT PUERTO RICO PR QATAR QA REUNION RE ROMANIA RO RUSSIAN FEDERATION RU RWANDA RW SAINT HELENA SH SAINT KITTS AND NEVIS KN SAINT LUCIA LC SAINT PIERRE AND MIQUELON PM SAINT VINCENT AND THE GRENADINES VC SAMOA WS SAN MARINO SM SAO TOME AND PRINCIPE ST SAUDI ARABIA SA SENEGAL SN SERBIA AND MONTENEGRO CS SEYCHELLES SC SIERRA LEONE SL SINGAPORE SG SLOVAKIA SK SLOVE
PAGE 232
Country Codes 232 Country Code SOMALIA SO SOUTH AFRICA ZA SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS GS SPAIN ES SRI LANKA LK SUDAN SD SURINAME SR SVALBARD AND JAN MAYEN SJ SWAZILAND SZ SWEDEN SE SWITZERLAND CH SYRIAN ARAB REPUBLIC SY TAIWAN, PROVINCE OF CHINA TW TAJIKISTAN TJ TANZANIA, UNITED REPUBLIC OF TZ THAILAND TH TIMOR-LESTE TL TOGO TG TOKELAU TK TONGA TO TRINIDAD AND TOBAGO TT TUNISIA TN TURKEY TR TURKMENISTAN TM TURKS AND CAICOS ISLANDS TC TUV
PAGE 233
Country Codes Country Code UNITED KINGDOM GB UNITED STATES US UNITED STATES MINOR OUTLYING ISLANDS UM URUGUAY UY UZBEKISTAN UZ VANUATU VU VENEZUELA VE VIET NAM VN VIRGIN ISLANDS, BRITISH VG VIRGIN ISLANDS, U.S.
PAGE 234
Country Codes 234 08 April 2009 Name-Value Pair API Developer Guide
PAGE 235
C State and Province Codes State and Province Codes Canadian Province or U.S.
PAGE 236
State and Province Codes 236 Canadian Province or U.S.
PAGE 237
State and Province Codes Canadian Province or U.S.
PAGE 238
State and Province Codes 238 08 April 2009 Name-Value Pair API Developer Guide
PAGE 239
D Currency Codes Currencies and Currency Codes Supported by PayPal Currency Currency Code Australian Dollar AUD Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF U.S.
PAGE 240
Currency Codes 240 08 April 2009 Name-Value Pair API Developer Guide
PAGE 241
E AVS and CVV2 Response Codes z “AVS Response Codes” on page 241 z “CVV2 Response Codes” on page 243 AVS Response Codes z AVS Response Codes for Visa, Mastercard, Discover, and American Express z AVS Response Codes for Maestro and Solo Name-Value Pair API Developer Guide 08 April 2009 241
PAGE 242
AVS and CVV2 Response Codes AVS Response Codes AVS Response Codes for Visa, MasterCard, Discover, and American Express AVS Code Meaning Matched Details A Address Address only (no ZIP) B International “A” Address only (no ZIP) C International “N” None NOTE: The transaction is declined. D International “X” Address and Postal Code E Not allowed for MOTO (Internet/Phone) transactions Not applicable NOTE: The transaction is declined.
PAGE 243
AVS and CVV2 Response Codes CVV2 Response Codes AVS Code Meaning Matched Details 4 Address not checked, or acquirer had no response. Service not available. Not applicable Null No AVS response was obtained. Default value of field.