Home

PayPal Website Payments Standard - 2009 - Button Manager API (SOAP) User Guide

1. PayPal does not generate code for options Button Hosting Buttons that you can view on the My Saved Buttons page of your PayPal profile are called hosted buttons because they reside on PayPal The API can create three kinds of buttons hosted encrypted and clear text Button Manager SOAP API June 2009 9 10 Website Payments Standard Button Manager API Overview Hosted Button Manipulation e Hosted buttons are stored on PayPal The parameters associated with this kind of button are Secure Hosted buttons provide the greatest flexibility because you can instruct PayPal to change them dynamically and PayPal maintains information about their state such as the inventory level associated with the button Encrypted buttons are not stored on PayPal The parameters associated with this kind of button are encrypted Encrypted buttons are similar to hosted buttons with regards to secure operation however you must update the web pages that use an encrypted button each time the button or its associated information changes You should only use an encrypted button if a hosted button cannot be used Clear text buttons are not stored on PayPal The parameters associated with this kind of button are not encrypted Clear text buttons are not hosted and are not encrypted They can be used dynamically because you can change the value of a parameter on the fly However if you use them recognize the risk that sensitive information can
2. each of which can include up to 10 possible selections Button Manager SOAP API June 2009 19 Button Manager API Reference BMCreateButton API Operation class ButtonManager eb AbstractRequestType XSDcomplexT ype BM Create ButtonRequest OptionDetails OptionDetailsType 0 5 XSDelements ButtonCode ebl ButtonCodeType 0 ButtonCountry ebl CountyCodeType 0 Buttonimage eblButtonimageT ype D ButtonimageURL xs sring 0 ButtonLanguage xs sting 0 ButtonSubType ebl ButtonSubT ypeType 0 ButtonType ebi ButtonTypeType 0 ButtonVar xs sring 0 BuyNowTex ebl BuyNowT extT ype 0 SubscribeText ebl SubscibeTextT ype 0 TexBox xs string 0 BMCreateButton Request Fields Field ButtonCode ButtonType ButtonSubType Description ebl ButtonCodeType Optional The kind of button code to create It is one of the following values e HOSTED A secure button stored on PayPal default for all buttons except View Cart and Unsubscribe e ENCRYPTED An encrypted button not stored on PayPal default for View Cart button e CLEARTEXT An unencrypted button not stored on PayPal default for Unsubscribe button ebl ButtonTypeType Required The kind of button you want to create It is one of the following values e BUYNOW Buy Now button e CART Add to Cart button e GIFTCERTIFICATE Gift Certificate button SUBSCRIBE Subscrib
3. invalid 11971 Invalid Data Inventory and or profit amp loss must be managed by item or an option with price when one is defined 11972 Invalid Data Option name index value specified does not exist 11973 Invalid Data ItemQty and or ItemQtyDelta must be an integer 11974 Invalid Data An item quantity or item quantity delta value cannot be specified when TrackInv is 0 11975 Invalid Data The number of option quantity or option quantity delta values specified is greater than the number of option selections in the saved button 11976 Invalid Data You must specify either option quantity or option quantity delta values with a valid integer value 11977 Invalid Data An option quantity or option quantity delta value must not be specified when TrackInv is 0 11978 Invalid Argument Item alert must be specified as a positive integer June 2009 Correcting This Error Button Manager SOAP API Button Manager API Reference MR BMGetlnventory API Operation Error Code Short Message Long Message Correcting This Error 11979 Invalid Argument Item alert must not be specified when TrackInv is 0 11980 Invalid Data The number of option alert values specified is greater than the number of option selections in the saved button 11981 Invalid Argument Option alert values must be specified as a positive integer 11982 Invalid Argument Option alert values cannot be specified when TrackInv is 0 11983 Invalid Argumen
4. small gt small 10 00 lt input type hidden name option amount0 lt option gt value 10 00 gt e Optional for Buy Now and Add to Cart buttons e Not used with Donate Subscribe or Buy Gift Certificate buttons option select1 Optional For priced options the value of the second option selection of 64 the on0 dropdown menu For example lt option value medium gt small 10 00 lt option gt input type hidden name option select value medium gt You can specify a maximum of ten option selections by incrementing the option selection index option select0 through option select9 NOTE A corresponding option selection in osO must also be set e Optional for Buy Now and Add to Cart buttons e Not used with Donate Subscribe or Buy Gift Certificate buttons Button Manager SOAP API June 2009 55 56 HTML Variables for Website Payments Standard HTML Variables for Payment Transactions Required or Character Name Optional Description Length option amountl Optional For priced options the amount that you want to charge for the 64 second option selection of the on0 dropdown menu For example lt option value small gt medium 15 00 lt option gt lt input type hidden name option amountl value 15 00 gt i You can specify a maximum of ten option amounts by incrementing the option amount index option amount0 through option amount9 NOTE A corresponding option selection in osO
5. Argument The email or merchant ID specified 1s invalid 11929 Invalid Data A cart button must have an item name and amount specified Code for email links and links in other documents that support external links June 2009 Button Manager SOAP API Button Manager API Reference MR BMUpdateButton API Operation Error Code Short Message Long Message Correcting This Error 11930 Invalid Data A gift certificate button must have a valid shopping URL specified 11931 Invalid Argument The subscription button text specified is invalid 11932 Invalid Data You must specify a corresponding number of entries for option names and selections 11933 Invalid Data You cannot skip index numbers for option selections Option selections must be specified sequentially 11934 Invalid Data You must specify the same number of entries for option prices and selections 11936 Invalid Data You cannot specify both an item price and prices for individual selections within an option 11937 Invalid Argument A text box name specified is invalid Text box names must not exceed 64 characters 11938 Invalid Argument The button code value specified is invalid 11940 Invalid Argument An option name specified is invalid Option names must not exceed 64 characters 11941 Invalid Argument An option selection value specified is invalid Option selection values must not exceed 64 characters 11942 Invalid Argument An option price value specified is inv
6. Manager API Overview ES Button Hosting lt form target paypal action https www sandbox paypal com cgi bin webscr method post lt input type hidden name cmd value s xclick lt input type hidden name hosted button id value 19218 gt table lt tr gt lt td gt lt input type hidden name on0 value Color gt Color lt td gt lt tr gt lt tr gt lt td gt lt select name os0 lt option value Red gt Red 10 00 lt option value Blue gt Blue 8 00 lt option value Green gt Green 12 00 lt select gt lt td gt lt tr gt lt tr gt lt td gt lt input type hidden name on1 value Size gt Size lt td gt lt tr gt lt tr gt lt td gt lt select name 0s1 gt lt option value Small Small lt option value Large gt Larg lt select gt lt td gt lt tr gt lt table gt lt input type hidden name currency code value USD gt lt input type image src https www sandbox paypal com en US i btn btn cart LG gif border 0 name submit alt gt lt img alt border 0 src https www sandbox paypal com en US i scr pixel gif width 1 height 1 gt lt form gt When you display a web page with this code this button appears Color Red 1000 v Size Small v add fo Can PayPal generated code for a link would be as follows https www sandbox paypal com cgi bin webscr cmd s xclick amp hosted button id 19218 For a link
7. Variables for Website Payments Standard E HTML Variables for Individual Items Required or Character Name Optional Description Length undefined Optional 1 allows buyers to specify the quantity 1 quantity e Optional for Buy Now buttons e Not used with other buttons weight Optional Weight of items If profile based shipping rates are configured with a basis of weight the sum of weight values is used to calculate the shipping charges for the transaction weight unit Optional The unit of measure if weight is specified Allowable values e lbs e kgs The defaults is Lbs on0 Optional First option field name and label The os0 variable contains 64 the corresponding value for this option field For example if on0 is size os0 could be large e Optional for Buy Now Subscribe and Add to Cart buttons e Not used with Donate or Buy Gift Certificate buttons onl Optional Second option field name and label The os1 variable 64 contains the corresponding value for this option field For example if on1 is color then os1 could be blue You can specify a maximum of 7option field names 6 with Subscribe buttons by incrementing the option name index on0 through on6 e Optional for Buy Now Subscribe and Add to Cart buttons e Not used with Donate or Buy Gift Certificate buttons Button Manager SOAP API June 2009 53 en HTML Variables for Website Payments Standard HTML Variables for Individual Items Required or Name Optional De
8. of the item less its cost multiplied by the change in the inventory level since the last call to BMSetInventory ebl ItemTrackingDetails Item tracking details for the button OptionIndex xs string Option index which identifies the button Option index 0 is the menu that contains the price if one exists otherwise it is the first menu without a price Character length and limitations 1 single byte alphanumeric character E ebl OptionTrackingDetails Option tracking details for menu items associated with the button SoldoutURL xs string The URL to which the buyer s browser is redirected when the inventory drops to 0 NOTE A value in this field also prevents a sale when the inventory drops to 0 otherwise sales can continue even when inventory is unavailable Character length and limitations 127 single byte alphanumeric characters Item Tracking Details Fields ItemNumber xs string The ID for an item associated with this button ItemOty xs string The current inventory level of the item associated with this button ItemOtyDelta xs string Not used ItemAlert xs string The quantity of the item associated with this button below which PayPal sends you an email notification Button Manager SOAP API June 2009 47 eam Button Manager API Reference BMGetlnventory API Operation ItemCost xs string The cost of the item associated with this button Option Tracking Details Fields OptionNumber xs string T
9. quantity2 NOTE The value for quantity must be a positive integer Null zero or negative numbers are not allowed The cost of shipping this item If you specify shipping and shipping is not defined this flat amount is charged regardless of the quantity of items purchased This use of the shipping variable is valid only for Buy Now and Add to Cart buttons Default If profile based shipping rates are configured buyers are charged an amount according to the shipping methods they choose The cost of shipping each additional unit of this item If omitted and profile based shipping rates are configured buyers are charged an amount according to the shipping methods they choose Valid only for Buy Now and Add to Cart buttons Transaction based tax override variable Set this to a flat tax amount to apply to the transaction regardless of the buyer s location This value overrides any tax settings set in your account profile Valid only for Buy Now and Add to Cart buttons Default Profile tax settings 1f any apply Transaction based tax override variable Set this to a 6 percentage that will be applied to amount multiplied the quantity selected during checkout This value overrides any tax settings set in your account profile Allowable values are numbers 0 001 through 100 Valid only for Buy Now and Add to Cart buttons Default Profile tax settings if any apply 52 June 2009 Button Manager SOAP API HTML
10. use e Technical HTML Variables on page 49 e HTML Variables for Individual Items on page 50 e HTML Variables for Payment Transactions on page 56 e HTML Variables for Shopping Carts on page 58 e HTML Variables for Subscribe Buttons on page 60 e HTML Variables for Displaying PayPal Checkout Pages on page 63 e HTML Variables for Prepopulating PayPal Checkout Pages on page 66 Technical HTML Variables Technical HTML variables control how PayPal responds technically when people click Buy Now Donation Subscribe Add to Cart and View Cart buttons or when third party or custom carts initiate payment processing with the Cart Upload command They also control how your buttons interact with special PayPal features Button Manager SOAP API June 2009 49 en HTML Variables for Website Payments Standard HTML Variables for Individual Items Allowable Values for the cmd HTML Variable Value of cmd Description _xclick The button that the person clicked was a Buy Now button _ donations The button that the person clicked was a Donate button _xclick subscriptions The button that the person clicked was a Subscribe button _oe gift certificate The button that the person clicked was a Buy Gift Certificate button _ cart For shopping cart purchases these additional variables specify the kind of shopping cart button that the person clicked e add Add to Cart buttons for the PayPal Shopping Cart e display View Car
11. 009 61 eun HTML Variables for Website Payments Standard HTML Variables for Subscribe Buttons Required or Character Name Optional Description Length src Optional Recurring payments Subscription payments recur unless 1 subscribers cancel their subscriptions before the end of the current billing cycle or you limit the number of times that payments recur with the value that you specify for srt Allowable values e 0 subscription payments do not recur e 1 subscription payments recur The default is 0 srt Optional Recurring times Number of times that subscription payments 1 recur Specify an integer above 1 Valid only if you specify src sra Optional Reattempt on failure If a recurring payment fails PayPal attempts 1 to collect the payment two more times before canceling the subscription Allowable values e 0 do not reattempt failed recurring payments e reattempt failed recurring payments before canceling The default is 0 no note Required Do not prompt payers to include a note with their payments 1 Allowable values for Subscribe buttons e 1 hide the text box and the prompt For Subscribe buttons always include no note and set it to 1 custom Optional User defined field which will be passed through the system and 255 returned in your merchant payment notification email This field will not be shown to your subscribers invoice Optional User defined field which must be unique with each subscripti
12. 10 itemQty lt itemAlert gt 2 lt itemAlert gt lt itemCost gt 4 lt itemCost gt lt itemTrackingDetails gt lt soldoutURL gt http www paypal com lt soldoutURL gt lt com paypal soap api BMSetInventoryRequestType gt Button Manager SOAP API June 2009 17 E Using the Button Manager API Tracking Inventory for a Button Using SOAP 18 June 2009 Button Manager SOAP API Button Manager API Reference The Button Manager API enables you to programatically create edit and delete Website Payment Standard buttons hosted on PayPal and track product inventory associated with these buttons You can also create non hosted buttons with the Button Manager API however button maintenance and inventory management are only supported for hosted buttons e BMCreateButton API Operation MUpdateButton API Operation MButtonSearch API Operation MCreateButton API Operation MManageButtonStatus API Operation MSetInventory API Operation B B B B B B MGetInventory API Operation BMCreateButton API Operation Use the BMCreateButton API operation to create a Website Payments Standard button You an create either a button that is hosted on PayPal or a non hosted button e BMCreateButton Request e BMCreateButton Response e BMCreateButton Errors BMCreateButton Request The request fields specify the characteristics of your button which include associated menu items related to the button You can specify up five menu items
13. BMGetButtonDetails API Operation Use the BMGetButtonDetails API operation to obtain information about a hosted Website Payments Standard button You can use this information to set the fields that have not changed when updating a button e BMGetButtonDetails Request e BMGetButtonDetails Response e BMUpdateButton Errors BMGetButtonDetails Request The request consists of only the ID of the hosted button whose details you want to obtain class ButtonManager abi AbstrisctRequestType XSDcomplexType BMGetButtonDetsilsRequest XSDelements HostedButtonlD xs string BMGetButtonDetails Request Fields Field Description HostedButtonID xs string Required The ID of the hosted button whose details you want to obtain BMGetButtonDetails Response 34 The response fields contain all non inventory information related to the button June 2009 Button Manager SOAP API Button Manager API Reference BMGetButtonDetails API Operation class ButtonManager eb AbstectResponse Type XSDcomplexT ype BMGetButtonDetails Response OptionDetails OptionDetailsType 0 5 XSDelements ButtonCode ebl ButtonCodeType 0 ButtonCountry ebl CountyCodeType 0 Buttonimage ebi ButtonimageT ype D ButtonimageURL xs string 0 ButtonLanguage s sting 0 ButtonSubType ebl ButtonSubT ypeType 0 ButtonType ebl ButtonT ypeType 0 ButtonVar xs amp rin
14. OTE You can access your My Saved Buttons page on PayPal by choosing My Saved Buttons from the Profile s Selling Preferences column If no buttons have been created the menu item is Create New Button You can use the API to create the following types of Website Payment Standard buttons e Buy Now e Add to Cart and View Cart e Donate e Buy Gift Certificate e Subscribe and Unsubscribe The following buttons are some of those that you can create using the Button Manager API Button Manager SOAP API June 2009 Website Payments Standard Button Manager API Overview Generated Button Code Generated Button Code When you create a button PayPal responds by providing code that you can paste into your web page or document PayPal generates code that you can use for the button which includes e HTML code for including the button in web pages e URL link code for adding buttons to email and documents that support links NOTE Not all buttons that can be created are available to merchants in every country for example German merchants cannot use Subscribe buttons even though they can be created through the API If you can create the button for the specified country using Create PayPal payment button on PayPal your merchant will be able to use the button The following example shows the PayPal code to display a hosted Add to Cart button for a wireless mouse June 2009 Button Manager SOAP API Website Payments Standard Button
15. PayPal Website Payments Standard Button Manager API SOAP For Professional Use Only Currently only available in English A usage Professional Uniquement Disponible en Anglais uniquement pour l instant Last updated June 2009 Button Manager SOAP API Document Number 10090 en US 200906 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 PayPal Europe Ltd is authorised and regulated by the Financial Services Authority in the United Kingdom as an electronic money institution PayPal FSA Register Number 226056 Notice of non liability PayPal Inc is providing the information in this document to you AS IS with all faults PayPal Inc makes no warranties of any kind whether express implied or statutory with respect to the information contained herein PayPal Inc assumes no liability for damages whether direct or indirect caused by errors or omissions or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein PayPal Inc reserves the right to make changes to any information herein without further notice Cont
16. Required The ID of the hosted button whose inventory you want to set June 2009 Button Manager SOAP API Button Manager API Reference ES BMSetInventory API Operation Field Description TrackInv xs string Required Whether to track inventory levels associated with the button It is one of the following values e 0 do not track inventory e 1 track inventory TrackPnl xs string Required Whether to track the gross profit associated with inventory changes It is one of the following values e 0 do not track the gross profit e 1 track the gross profit NOTE The gross profit is calculated as the price of the item less its cost multiplied by the change in the inventory level since the last call to BMSetInventory ebl ItemTrackingDetails Optional Item tracking details for the button OptionIndex xs string Optional Option index which identifies the button Option index 0 is the menu that contains the price if one exists otherwise it is the first menu without a price Character length and limitations 1 single byte alphanumeric character ebl OptionTrackingDetails Optional Option tracking details for menu items associated with the button SoldoutURL xs string Optional The URL to which the buyer s browser is redirected when the inventory drops to 0 NOTE Specifying a URL in this field also prevents a sale when the inventory drops to 0 otherwise sales can continue even when inventory is unavaila
17. The URL of the page on the merchant website that buyers return to when they click the Continue Shopping button on the PayPal Shopping Cart page upload See Upload the contents of a third party shopping cart or a custom 1 description shopping cart This variable must be set as follows upload 1 The alternatives are the add 1 variable and the display 1 variable which are used with the PayPal Shopping Cart HTML Variables for Subscribe Buttons HTML variables for Subscribe buttons set the terms of subscriptions and their recurring payments 60 June 2009 Button Manager SOAP API HTML Variables for Website Payments Standard E HTML Variables for Subscribe Buttons HTML Variables for Subscribe Buttons Required or Character Name Optional Description Length business Required Your PayPal ID or an email address associated with your PayPal account Email addresses must be confirmed item name Optional Description of item being sold maximum 127 characters If you are collecting aggregate payments this can include a summary of all items purchased tracking numbers or generic terms such as subscription If omitted customer will see a field in which they have the option of entering an Item Name currency co Optional The currency of prices for trial periods and the subscription The 3 de default is USD al Optional Trial period 1 price For a free trial period specify 0 pl See Trial period 1 duration Required if you spe
18. ageButtonStatus API Operation Option Details Fields Field Description OptionName xs string Optional The menu name OptionSelectionDetails ns OptionSelectionDetailsType Menu items OptionSelectionDetails OptionSelection xs string Optional The menu item s name Price xs string Optional The price associated with the first menu item NOTE If you specify a price you cannot set a button variable to amount BMGetButtonDetails Errors Error Code Short Message Long Message Correcting This Error 10001 Internal Error Internal Error 11950 Invalid Data A hosted button ID must be specified 11951 Invalid Argument The hosted button ID specified is invalid 11951 Invalid Argument The hosted button ID specified is invalid 11992 Invalid Argument You do not have permissions to access this button Please check the hosted button ID and try again BMManageButtonStatus API Operation Use the BMManageButtonStatus API operation to change the status of a hosted button Currently you can only delete a button e BMManageButtonStatus Request e BMManageButtonStatus Response e BMUpdateButton Errors Button Manager SOAP API June 2009 37 eam Button Manager API Reference BMManageButtonStatus API Operation BMManageButtonStatus Request The request specifies the hosted button s ID and the status to which you want to set the button class ButtonManager eblAbstractRequestType XSDoom plexT ypa BMM
19. alid Make sure any punctuation marks are in the correct places 11943 Invalid Argument The button country value specified is invalid 11945 Invalid Data The button country and language code combination specified is invalid 11947 Invalid Argument The tax rate specified is invalid Make sure any punctuation marks are in the correct places and value specified is in the range 0 0 to 100 11948 Invalid Argument The amount specified is invalid Make sure any punctuation marks are in the correct places Button Manager SOAP API June 2009 31 ean Button Manager API Reference BMButtonSearch API Operation BMButtonSearch API Operation Use the BMButtonSearch API operation to obtain a list of your hosted Website Payments Standard buttons e BMButtonSearch Request e BMButtonSearch Response e BMButtonSearch Errors BMButtonSearch Request The request contains optional fields that are not currently used All hosted buttons are automatically requested class ButtonManager eb AbstectRequestType XSDcomplexT ype BM Button SearchRequest XSDelements EndDate xsdateT ime 0 StanDate xsdateT ime 0 BMButtonSearch Request Fields Field Description StartDate xs dateTime Required Starting date for the search such as 12 01 09 EndDate xs dateTime Optional Ending date for the search such as 12 31 09 BMButtonSearch Response The response contains a list of all hosted buttons and their associate
20. anage Button SttusRequest XSDelements ButonStatus eblButonStatusType 0 HosedButioniD xs sting 0 BMManageButtonStatus Request Fields Field Description HostedButtonID xs string Required The ID of the hosted button whose status you want to change ButtonStatus ebl ButtonStatusType Required The new status of the button It is one of the following values e DELETE the button is deleted from PayPal BMManageButtonStatus Response The response does not include any fields that are specific to the BMManageButtonStatus API operation BMManageButtonStatus Errors Error Code Short Message Long Message Correcting This Error 10001 Internal Error Internal Error 11950 Invalid Data A hosted button ID must be specified 11951 Invalid Argument The hosted button ID specified is invalid 11951 Invalid Argument The hosted button ID specified is invalid 11992 Invalid Argument You do not have permissions to access this button Please check the hosted button ID and try again 38 June 2009 Button Manager SOAP API Button Manager API Reference ES BMSetInventory API Operation Error Code Short Message Long Message Correcting This Error 11993 Invalid Argument The button status value specified is not valid BMSetlnventory API Operation Use the BMSet Inventory API operation to set the inventory level and inventory management features for the specified button When you
21. arty calling the API directly may specify an unregistered email and create an unencrypted button only e A 3rd Party calling the API on behalf of a registered merchant must specify an email address associated with the merchant account Character length and limitations 127 single byte characters item number Item number or ID Character length and limitations 127 single byte alphanumeric characters le If specified it overrides the value set in the ButtonCode field For a complete list of HTML variables and complete information see HTML Variables for Website Payments Standard Creating a Button Using SOAP The example sets up a SOAP request message to create a button 14 June 2009 Button Manager SOAP API Using the Button Manager API Creating a Button Using SOAP lt com paypal soap api BMCreateButtonRequestType gt lt buttonType gt value gt m value CART m value value gt lt buttonType gt lt buttonCode gt value gt m value HOSTED m value lt _ value gt lt buttonCode gt lt buttonSubType gt lt value gt m value PRODUCTS m value value buttonSubType lt buttonVar gt lt string gt business XX usbiz paypal com lt string gt lt string gt item name Item 123 string lt string gt item number 1234 lt string gt lt string gt shipping 0 50 lt string gt lt string gt tax rate 2 50 lt string gt string addressl string string s
22. be altered or stolen Hosted Button Manipulation When you create a hosted button the response includes an ID that allows you to manipulate the button using the Button Manager API Specifically you can Get a list of all hosted buttons defined which allows you to obtain a list of all your buttons for further programatic manipulation Get details about a hosted button which allows you to identify the parameters and values associated with a button Update a hosted button which allows you to change individual parameters such as price in a hosted button Manage hosted button status currently you can only delete a button Get and set inventory information associated with the button Inventory Management Using Hosted Buttons If you use hosted buttons you can set inventory values for the item associated with the button and get inventory values for the item You can also track inventory on options within an item such as color size and so on If you enable inventory management for a button PayPal tracks inventory for you and also lets your buyer know whether the item is sold out You can specify inventory tracking on an item by item basis and also by option such as color or size within the item June 2009 Button Manager SOAP API Website Payments Standard Button Manager API Overview Button Manager API Summary You are alerted by e mail if the inventory on hand falls below the threshold you specify If an item is sol
23. ble Character length and limitations 127 single byte alphanumeric characters Item Tracking Details Fields ItemNumber xs string Optional The ID for an item associated with this button ItemQty xs string The quantity you want to specify for the item associated with this button Specify either the absolute quantity in this field or the change in quantity in the quantity delta field Button Manager SOAP API June 2009 41 42 Button Manager API Reference BMSetInventory API Operation ItemQtyDelta ItemAlert ItemCost xs string The change in quantity you want to specify for the item associated with this button Specify either the change in quantity in this field or the absolute quantity in the item quantity field xs string Optional The quantity of the item associated with this button below which PayPal sends you an email notification xs string Optional The cost of the item associated with this button Option Tracking Details Fields OptionNumber OptionQty OptionSelect OptionQtyDelta OptionAlert OptionCost xs string Optional The menu item s ID for an option in a dropdown menu xs string The quantity you want to specify for the option associated with this menu item Specify either the absolute quantity in this field or the change in quantity in the quantity delta field xs string Optional The menu item s name in a dropdown menu xs string The change in quantity you want
24. cify al Specify an 2 description integer value in the allowable range for the units of duration that you specify with t1 el See Trial period 1 units of duration Required if you specify a1 1 description Allowable values e D for days allowable range for p1 is 1 to 90 e W for weeks allowable range for p1 is 1 to 52 e M for months allowable range for p1 is 1 to 24 e Y for years allowable range for p1 is 1 to 5 a2 Optional Trial period 2 price Can be specified only if you also specify a1 p2 See Trial period 2 duration Required if you specify a2 Specify an 2 description integer value in the allowable range for the units of duration that you specify with t2 t2 See Trial period 2 units of duration Allowable values 1 description e D for days allowable range for p2 is 1 to 90 e W for weeks allowable range for p2 is 1 to 52 e M for months allowable range for p2 is 1 to 24 e Y for years allowable range for p2 is 1 to 5 a3 Required Regular subscription price p3 Required Subscription duration Specify an integer value in the allowable 2 range for the units of duration that you specify with t3 t3 Required Regular subscription units of duration Allowable values 1 D for days allowable range for p3 is 1 to 90 W for weeks allowable range for p3 is 1 to 52 M for months allowable range for p3 is 1 to 24 e e e e Y for years allowable range for p3 1s 1 to 5 Button Manager SOAP API June 2
25. ctions as test boxes NOTE A corresponding option field on0 through on6 must defined e Optional for Buy Now Subscribe and Add to Cart buttons e Not used with Donate or Buy Gift Certificate buttons The cardinal number of the option field on0 through on9 that has product options with different prices for each option You must include option index if the option field with prices is not on0 e Optional for Buy Now and Add to Cart buttons e Not used with Donate Subscribe or Buy Gift Certificate buttons Default 0 64 or 200 See description 64 or 200 See description 54 June 2009 Button Manager SOAP API HTML Variables for Website Payments Standard E HTML Variables for Individual Items Required or Character Name Optional Description Length option select0 Optional For priced options the value of the first option selection of 64 the on0 dropdown menu The values must match exactly as the next sample code shows lt option value small gt small 10 00 lt option gt lt input type hidden name option select0 value small gt e Optional for Buy Now and Add to Cart buttons e Not used with Donate Subscribe or Buy Gift Certificate buttons option amount0 Optional For priced options the amount that you want to charge for the 64 first option selection of the on0 dropdown menu Use only numeric values the currency is taken from the currency code variable For example option value
26. d characteristics 32 June 2009 Button Manager SOAP API Button Manager API Reference ES BMButtonSearch API Operation class ButtonManager eblAbstractResponse Type XSDoomplexType BMButtonSearchResponse XSDelements ext ref 5 ebl ButtonSearchResult 0 100 class ButtonManagerTypes XSDcomplexT ype Button SearchResultType XSDelements ButtonType xsstring 0 HosedButtonlD xs sting 0 ltemName xsstring 0 ModifyDate xsdsteTime 0 BMButtonSearch Response Fields Name Description ebl ButtonSearchResult Search results ButtonSearchResult HostedButtonID xs string The hosted button ID HButtonType xs string The hosted button ID ItemName xs string The item name ModifyDate xs dateTime The date created or last changed BMButtonSearch Errors Error Code Short Message Long Message Correcting This Error 10001 Internal Error Internal Error Button Manager SOAP API June 2009 33 Button Manager API Reference BMGetButtonDetails API Operation Error Code Short Message Long Message Correcting This Error 11994 11997 11998 11999 Search Warning Invalid Argument Invalid Argument Invalid Argument You have exceeded the maximum number of buttons that can be returned Please adjust your seach parameters if required A start date value must be specified The start date specified is invalid The end date specified is invalid
27. d out you can specify whether or not to accept a payment anyway Optionally you can specify a URL to which your buyer s browser is redirected if the item is sold out Additionally you can enable profit and loss tracking for an item or option associated with a button If you enable this feature you must provide the cost of the item or option PayPal then calculates your gross profit which is the selling price of the item less the specified cost Button Manager API Summary The Button Manager API is available for both NVP and SOAP API Operation Description BMCreateButton Create button code BMUpdateButton Update a hosted button BMManageButtonStatus Delete a button BMGetButtonDetails Obtain information about the parameters associated with a button BMButtonSearch Obtain a list of all buttons BMGetInventory Obtain the inventory levels associated with a button BMSetInventory Specify the inventory levels associated with a button Granting Third Party Permission for APIs If you allow a shopping cart or another party to create buttons on your behalf you must grant the party permission to execute Button Manager API operations for you To grant third party permissions 1 Log in to your PayPal account Select My Account Profile Click API Access from the Profile Summary Click Grant API Permission Click to Configure a custom API authorization Enter your Partner API Username as specified by your shopping ca
28. discount rate must also be specified as greater than or equal to 0 for discount rate2 to take effect Valid only for Buy Now and Add to Cart buttons discount num Optional Number of additional quantities of the item to which the discount applies Applicable when you use discount amount2 or discount rate2 Use this variable to specify an upper limit on the number of discounted items Valid only for Buy Now and Add to Cart buttons Button Manager SOAP API June 2009 51 eun HTML Variables for Website Payments Standard HTML Variables for Individual Items Name Required or Optional Character Description Length item name item number quantity shipping shipping2 tax tax rate See description Optional Optional Optional Optional Optional Optional Description of item If omitted payers enter their own name 127 at the time of payment e Optional for Buy Now Donate Subscribe and Add to Cart buttons e Not used with Buy Gift Certificate buttons Pass through variable for you to track product or service 127 purchased or the contribution made The value you specify passed back to you upon payment completion Number of items If profile based shipping rates are configured with a basis of quantity the sum of quantity values is used to calculate the shipping charges for the transaction PayPal appends a sequence number to uniquely identify the item in the PayPal Shopping Cart e g quantityl
29. e button DONATE Donate button UNSUBSCRIBE Unsubscribe button VIEWCART View Cart button ebl ButtonSubTypeType Optional The use of button you want to create It is one of the following values e PRODUCTS button is used to purchase products default for Buy Now and Add to Cart buttons e SERVICES button is used to purchase services 20 June 2009 Button Manager SOAP API Button Manager API Reference E BMCreateButton API Operation Field Description ButtonVar xs string Optional HTML standard button variables which are described in HTML Variables for Website Payments Standard Itis a list of variables in which n is a digit between 0 and 999 inclusive do not include leading zeros Character length and limitations 63 single byte alphanumeric characters each OptionDetails ns OptionDetailsType Optional Menu items TextBox xs string Optional Text description for a menu item It is a list of variables in which n is a digit between 0 and 1 inclusive ButtonImage ebl ButtonImageType Optional The kind of button image It is one of the following values e REG regular default unless a button URL is specified e SML small e CC small button image with credit card logos not applicable for Unsubscribe or View Cart buttons NOTE Specify either the kind of button image or the URL ButtonImageURL xs string Optional The button s URL NOTE Specify either the
30. entries for option prices and selections 11936 Invalid Data You cannot specify both an item price and prices for individual selections within an option June 2009 Button Manager SOAP API Button Manager API Reference ES BMUpdateButton API Operation Error Code Short Message Long Message Correcting This Error 11937 Invalid Argument A text box name specified is invalid Text box names must not exceed 64 characters 11938 Invalid Argument The button code value specified is invalid 11940 Invalid Argument An option name specified is invalid Option names must not exceed 64 characters 11941 Invalid Argument An option selection value specified is invalid Option selection values must not exceed 64 characters 11942 Invalid Argument An option price value specified is invalid Make sure any punctuation marks are in the correct places 11943 Invalid Argument The button country value specified is invalid 11945 Invalid Data The button country and language code combination specified is invalid 11947 Invalid Argument The tax rate specified is invalid Make sure any punctuation marks are in the correct places and value specified is in the range 0 0 to 100 11948 Invalid Argument The amount specified is invalid Make sure any punctuation marks are in the correct places BMUpdateButton API Operation Use the BMUpdateButton API operation to modify a Website Payments Standard button that is hosted on PayPal This op
31. ents Preface 2 2 2 2 2 2 2 2 2 2 2 2 25 25 293b Intended AUdIlemnce ue x soa eR Rec b ee deo rene 5 Revision History ag nonno Be awd eee AAA 5 Chapter 1 Website Payments Standard Button Manager API Overview 7 Button Manager Introduction LL 7 Generated Button Code a 8 Button Hosting cs x Loo moe Pe ee eae ala 9 Hosted Button Manipulation 22s 10 Inventory Management Using Hosted Buttons aa 10 Button Manager API Summary LL 11 Granting Third Party Permission for APIS LL 11 Chapter 2 Using the Button Manager API 13 Specifying HTML Variables o 13 Creating a Button Using SOAP 2 2 a 14 Tracking Inventory for a Button Using SOAP 2 2 2205 4 16 Chapter 3 Button Manager API Reference 19 BMCreateButton API Operation e 19 BMCreateButton Request 222222 19 BMCreateButton Response e 23 BMCreateButton Errors 2 ll sls ess 24 BMUpdateButton API Operation oaoa a 2 220002 ee eee 25 BMUpdateButton Request e 25 BMUpdateButton Response 0 000220 ee eee 29 BMUpdateButton Errors aa 30 BMButtonSearch API Operation aoaaa 32 BMButtonSearchRequest a a eee ee 32 BMButtonSearchResponse 32 BMButtonSearch Errors 2 a 33 Button Manager SOAP API June 2009 eat Contents BMG
32. er API SOAP TABLE P 1 Revision History Date Description 06 03 09 Added HTML Variable appendix and updated for version 57 0 03 31 09 Initial draft Button Manager SOAP API June 2009 ms Revision History 6 June 2009 Button Manager SOAP API Website Payments Standard Button Manager API Overview The Website Payments Standard Button Manager API allows you to programatically create manage edit and delete Website Payment Standard buttons which are the same kind of buttons that you can create from the PayPal Profile Hosted buttons created by this API reside on PayPal and can use all features including inventory management however you can use this API to create code for non hosted Website Payment Standard buttons as well e Button Manager Introduction e Generated Button Code e Button Hosting e Hosted Button Manipulation e Inventory Management Using Hosted Buttons e Button Manager API Summary e Granting Third Party Permission for APIs Button Manager Introduction You should consider creating and managing your buttons with the Button Manager API when you are creating more than just a few Website Payment Standard buttons or when you manage buttons for others for example if you provide a shopping cart for merchants The Button Manager API enables you to manage Website Payment Standard buttons programatically in the same way that you can manage them on PayPal from the My Saved Buttons page of your Profile N
33. eration replaces all fields in the specified button therefore you must specify a value fore each field you want to include for the button whether or not it changed e BMUpdateButton Request e BMUpdateButton Response e BMUpdateButton Errors BMUpdateButton Request The hosted button ID identifies the button you want to modify The remaining request fields specify the characteristics of your button Button Manager SOAP API June 2009 25 ean Button Manager API Reference BMUpdateButton API Operation class ButtonManager eb AbstractRequestType XSDcomplexT ype BM Update ButtonRe quest OptionDetails OptionDetailsType 0 5 XSDelements ButtonCode ebl ButtonCodeType 0 ButtonCountry ebl CountyCodeType 0 Buttonimage eblButtonimageT ype D ButtonimageURL xs sring 0 ButtonLanguage xs string 0 ButtonSubType ebl ButtonSubTypeType 0 ButtonType ebl ButtonT ypeType 0 ButtonVar xs amp ring 0 BuyNowT ex ebl BuyNowT exT ype 0 HostedButtonID xsstring SubscribeText ebl SubsosbeTextT ype 0 TexBox xsstring 0 BMUpdateButton Request Fields Field Description HostedButtonID xs string Required The ID of the hosted button you want to modify ButtonType ebl ButtonTypeType Required The kind of button you want to update It is one of the following values e BUYNOW Buy Now button CART Add to Cart button GIFTCERTIFICATE Gift Certificate but
34. es Spanish default e en English Netherlands e nl Dutch default e en English Poland e pl Polish default e en English Spain e es Spanish default e en English Switzerland e de German default United States fr French en English en English default fr French es Spanish zh Chinese BMUpdateButton Response The response contains the hosted button ID code for HTML in a website and code for a link in email Button Manager SOAP API June 2009 29 30 Button Manager API Reference BMUpdateButton API Operation class ButtonManager eblAbstractResponse Type XSDcom plexT ype BM UpdateButtonRe sponse XSDelements Email xsstring 0 HostedButtoniD xsstring 0 Mobile xssring 0 Webste xs sring BMUpdateButton Response Fields Field Description Website xs string HTML code for web pages Email xs string HostedButtonID xs string ID of a PayPal hosted button BMUpdateButton Errors Error Code Short Message Long Message Correcting This Error 10001 Internal Error Internal Error 11923 Invalid Argument The button image value specified is invalid 11924 Invalid Argument The button image URL specified is invalid 11925 Invalid Argument The button type specified is invalid 11926 Invalid Data One of the parameters specified using ButtonVar is invalid 11927 Invalid Argument The buy now button text specified is invalid 11928 Invalid
35. etButtonDetails API Operation 20002200 eee 34 BMGetButtonDetails Request 34 BMGetButtonDetails Response e eee 34 BMGetButtonDetails Errors s s sa een 37 BMManageButtonStatus API Operation LL 37 BMManageButtonStatus Request 38 BMManageButtonStatus Response LL 38 BMManageButtonStatus Errors ooa aa a 38 BMSetlnventory API Operation o 39 BMSetlnventory Request LL 39 BMSetlnventory Response 0 42 BMSetlnventory Errors gt a lt ss 43 BNGetlnventory API Operation LL 45 BMGetlnventory Request 2s 46 BMGetlnventory Response es 46 BMGetlnventory Errors LL 48 Chapter A HTML Variables for Website Payments Standard 49 Technical HTML Variables e eq sa wahoe ens 49 HTML Variables for Individual tems ens 50 HTML Variables for Payment Transactions lll 56 HTML Variables for Shopping Carts o e 58 HTML Variables for Subscribe Buttons llle 60 HTML Variables for Displaying PayPal Checkout Pages 63 HTML Variables for Prepopulating PayPal Checkout Pages 66 4 June 2009 Button Manager SOAP API Preface This document describes the Button Manager API for SOAP Intended Audience This document is intended for merchants and developers implementing Website Payment Standard buttons using an API Revision History Revision history for Website Payments Standard Button Manag
36. fault No handling charges are included Passthrough variable you can use to identify your invoice number 127 for this purchase Default No variable is passed back to you The cost of shipping the entire order contained in third party shopping carts This use of the shipping variable is valid only for the Cart Upload command Default If profile based shipping rates are configured buyers are charged an amount according to the shipping methods they choose Cart wide tax overriding any individual item tax x value If profile based shipping rates are configured with a basis of weight PayPal uses this value to calculate the shipping charges for the transaction This value overrides the weight values of individual items The unit of measure if weight cart is specified Allowable values e lbs e kgs The default value is 1bs Button Manager SOAP API June 2009 57 eun HTML Variables for Website Payments Standard HTML Variables for Shopping Carts HTML Variables for Shopping Carts HTML variables for shopping carts can be used with Add to Cart buttons as well as with third party shopping carts or custom carts that initiate payment processing with the Cart Upload command 58 June 2009 Button Manager SOAP API HTML Variables for Website Payments Standard ES HTML Variables for Shopping Carts HTMLVariables for Shopping Carts Required Characte Name or Optional Description r Length add See Add an ite
37. g 0 BuyNowTex ebl BuyNowTexT ype 0 Email xs sring 0 HostedButtonID xsstring PD Mobile xsstring 0 SubscribeText ebl SubscibeTextT ype 0 TexBox xs string D Website xsstring D BMGetButtonDetails Response Fields Field Description ButtonType ButtonCode ButtonSubType HostedButtonID ebl ButtonTypeType The kind of button It is one of the following values BUYNOW Buy Now button CART Add to Cart button GIFTCERTIFICATE Gift Certificate button SUBSCRIBE Subscribe button DONATE Donate button UNSUBSCRIBE Unsubscribe button VIEWCART View Cart button ebl ButtonCodeType The kind of button code It is one of the following values HOSTED A secure button stored on PayPal ENCRYPTED An encrypted button not stored on PayPal CLEARTEXT An unencrypted button not stored on PayPal ebl ButtonSubTypeType The use of button It is one of the following values PRODUCTS button is used to purchase products SERVICES button is used to purchase services xs string ID of a PayPal hosted button Button Manager SOAP API June 2009 35 36 Button Manager API Reference BMGetButtonDetails API Operation Field Description Website Email ButtonVar OptionDetails TextBox ButtonImage ButtonImageURL BuyNowText SubscribeText ButtonCountry ButtonLanguage xs st
38. h the country identified by the country code Country Button Language Options All countries not identified below Austria Belgium Canada China worldwide France Germany Hong Kong Italy en English default de German default en English en English default nl Dutch fr French en English default fr French en English default zh Chinese fr French default en English de German default en English zh Chinese default en English it Italian default en English 22 June 2009 Button Manager SOAP API Button Manager API Reference ES BMCreateButton API Operation Country Button Language Options Japan e ja Japanese default e en English Mexico e es Spanish default e en English Netherlands e nl Dutch default e en English Poland e pl Polish default e en English Spain e es Spanish default e en English Switzerland e de German default fr French e en English United States en English default fr French es Spanish zh Chinese BMCreateButton Response The response contains an ID if the button is hosted on PayPal and code for HTML in a website and for a link in email class ButtonManager eblAbstractResponse Type XSDcom plexT ypa BMCreateButtonResponse XS Delements Email xsstring 0 HostedButtoniD xsstring D Mobile xssring 0 Webste xs sring BMCrea
39. he menu item s ID for an option in a dropdown menu OptionQty xs string The current inventory level of the option associated with this menu item OptionSelect xs string The menu item s name in a dropdown menu OptionQtyDelta xs string Not used OptionAlert xs string The quantity of the option associated with this menu item below which PayPal sends you an email notification OptionCost xs string The cost of the option associated with this menu item BMGetlnventory Errors Error Code Short Message Long Message Correcting This Error 10001 Internal Error Internal Error 11950 Invalid Data A hosted button ID must be specified 11951 Invalid Argument The hosted button ID specified is invalid 11953 Invalid Data You can only track inventory and profit amp loss for buy now cart or subscription buttons 11991 Invalid Data The hosted button id specified does not have any inventory or cost associated with it 11992 Invalid Argument You do not have permissions to access this button Please check the hosted button ID and try again 48 June 2009 Button Manager SOAP API HTML Variables for Website Payments Standard This appendix provides reference information for all HTML variables supported for use with Buy Now Donation Subscribe Add to Cart and View Cart buttons as well as HTML variables supported the Cart Upload command Read the following topics to learn about the kinds of HTML variables that you can
40. k The default is 0 June 2009 Button Manager SOAP API HTML Variables for Website Payments Standard EE HTML Variables for Displaying PayPal Checkout Pages Name Required or Optional Description Character Length lc no note cn no shipping return rm Optional Optional Optional Optional Optional Optional The language of the login or sign up page that subscribers see when they click the Subscribe button If unspecified the language is determined by a PayPal cookie in the subscriber s browser If there is no PayPal English For allowable values see cookie the default language is U S Do not prompt payers to include a note with their payments Allowable values e 0 provide a text box and prompt for the note e hide the text box and the prompt The default is 0 Label that appears above the and will not appear in any of note field This value is not saved your notifications If omitted the default label above the note field is Add special instructions to merchant The cn variable is not valid with Subscribe buttons or if you include no note 1 Do not prompt payers for shipping address Allowable values e 0 prompt for an address but do not require one e 1 do not prompt for an address e 2 prompt for an address and require one The default is 0 The URL to which the payer completing the payment for displays a Thank you for y
41. kind of button image or the URL BuyNowText ebl BuyNowTextType Optional The button text for a Buy Now button It is one of the following values e BUYNOW button text is Buy Now default e PAYNOW button text is Pay Now SubscribeText ebl SubscribeTextType Optional The button text for a Subscribe button It is one of the following values e BUYNOW button text is Buy Now e SUBSCRIBE button text is Subscribe default ButtonCountry ebl CountryCodeType Optional The country in which the transaction occurs See Country Codes for a list of country codes By default it is the merchant s country of registration with PayPal ButtonLanguage xs string Optional The language in which to display the button text It must be compatible with the country code Character length and limitations 2 single byte alphanumeric characters Button Manager SOAP API June 2009 21 Button Manager API Reference BMCreateButton API Operation Option Details Fields Field Description Opt ionName OptionSelectionDetails xs string Optional The menu name ns OptionSelectionDetailsType Menu items OptionSelectionDetails OptionSelection Price xs string Optional The menu item s name xs string Optional The price associated with the first menu item NOTE If you specify a price you cannot set a button variable to amount Button Language Options The button language must be compatible wit
42. m to the PayPal Shopping Cart 1 description This variable must be set as follows add 1 The alternative is the display 1 variable which displays the contents of the PayPal Shopping Cart to the buyer If both add and display are specified display takes precedence amount Required Price of the item or the total price of all items in the shopping cart business Required Your PayPal ID or an email address associated with your PayPal account Email addresses must be confirmed discount amount Optional Single discount amount to be charged cart wide _cart It must be less than the selling price of all items combined in the cart This variable overrides any individual item discount_amount_x values if present Applies only to the Cart Upload command discount amount Optional The discount amount associated with item x Xx It must be less than the selling price of the associated item This amount is added with any other item discounts in the cart Applies only to the Cart Upload command discount rate c Optional Single discount rate percentage to be charged cart wide art It must be set to a value less than 100 The variable overrides any individual item discount rate x values if present Applies only to the Cart Upload command discount rate x Optional The discount rate associated with item x It must be set to a value less than 100 The variable takes into account all quantities of item x Applies only to the Car
43. must also be set e Optional for Buy Now and Add to Cart buttons e Not used with Donate Subscribe or Buy Gift Certificate buttons HTML Variables for Payment Transactions HTML variables for payment transactions provide information about entire transactions regardless of the individual items involved with the payment You can use these variables with Add to Cart buttons and the Cart Upload command June 2009 Button Manager SOAP API HTML Variables for Website Payments Standard lA HTML Variables for Payment Transactions HTML Variables for Payment Transactions Name address override currency code custom handling invoice shipping tax cart weight cart weight unit Required or Optional Optional Optional Optional Optional Optional Optional Optional Optional Optional Character Description Length 1 The address specified in prepopulation variables overrides the 1 PayPal member s stored address The payer is shown the passed in address but cannot edit it No address is shown if the address is not valid such as missing required fields like country or is not included at all The currency of the payment The default is USD 3 Passthrough variable never presented to the payer 256 Default No variable is passed back to you Handling charges This is not quantity specific The same handling cost applies regardless of the number of items on the order De
44. n is defined Limitations Value must be a positive number No currency symbol Must have two decimal places decimal separator must be a period and the optional thousands separator must be a comma a3 Price of subscription Must be specified for Subscribe buttons Value must be a positive number No currency symbol Must have two decimal places decimal separator must be a period and the optional thousands separator must be a comma p3 Regular billing cycle Must be specified for Subscribe buttons Limitations Must be a positive integer greater than 0 and less than or equal to 30 t3 Regular billing cycle units Must be specified for Subscribe buttons shopping url URL where recipients can shop and redeem gift certificates Required for Gift Certificate buttons Character length and limitations 255 single byte alphanumeric characters Button Manager SOAP API June 2009 13 eat Using the Button Manager API Creating a Button Using SOAP HTML Variable Notes no note Must be specified for Subscribe buttons Enables a subscriber to not be prompted to include a note with the subscription a function which PayPal subscriptions does not support This variable must be included and the value must be set to 1 business Secure Merchant ID or Email Address When omitted defaults to the secure merchant ID of the merchant If an email address is specified then it the following requirements apply e A merchant or 3rd P
45. nager ebl AbstectRequestType XSDcomplexT ype BMGetinv entoryRequest XSDelements HostedButtoniD xs string BMGetlnventory Request Fields Field Description HostedButtonID xs string Required The ID of the hosted button whose inventory information you want to obtain BMGetlnventory Response The response fields contain inventory information related to the button class ButtonManager ebl AbstrisctResponseType XSDcomplexT ype BMGetinv entoryResponse XSDelements ext ref 3 eblitemT racking Details 0 1 ext ref 4 ebl OptonT rackingDetails 0 10 HosedButtonlD xs sting Optonindex xs string 0 OptionName xs sting 0 SoldoutURL xs sting 0 Trackinv xs sting TrackPnl xs string BMGetlnventory Response Fields Field Description HostedButtonID xs string The ID of the hosted button whose inventory you want to set 46 June 2009 Button Manager SOAP API Button Manager API Reference MR BMGetlnventory API Operation Field Description TrackInv xs string Whether to track inventory levels associated with the button It is one of the following values e 0 do not track inventory e 1 track inventory TrackPnl xs string Whether to track the gross profit associated with inventory changes It is one of the following values e 0 do not track the gross profit e 1 track the gross profit NOTE The gross profit is calculated as the price
46. ngth night Optional The three digit prefix for U S phone numbers or the entire See phone b phone number for phone numbers outside the U S excluding description country code This will prepopulate the payer s home phone number night Optional The four digit phone number for U S phone numbers This will See phone c prepopulate the payer s home phone number description state Optional State use Official U S Postal Service Abbreviations 2 zip Optional Postal code 32 Button Manager SOAP API June 2009 67 a HTML Variables for Website Payments Standard HTML Variables for Prepopulating PayPal Checkout Pages 68 June 2009 Button Manager SOAP API
47. nv value must be specified 11955 Invalid Data A TrackPnl value must be specified 11956 Invalid Argument The TrackInv value specified is invalid 11957 Invalid Argument The TrackPnl value specified is invalid 11958 Invalid Data You cannot specify both an ItemQty and ItemQtyDelta value 11959 Invalid Data You cannot specify both an OptionQty and OptionQtyDelta value 11960 Invalid Data You cannot specify item level or option level inventory when TrackInv is 0 11961 Invalid Data You must either track inventory by item or by option when TrackInv is 1 It cannot be tracked by both together or none at all Button Manager SOAP API June 2009 43 44 Button Manager API Reference BMSetInventory API Operation Error Code Short Message Long Message 11964 Invalid Data You must either track inventory and or track profit amp loss 11965 Invalid Data You cannot track inventory by item and cost by option at the same time or vice versa 11966 Invalid Argument Item number specified is invalid It must be a string less than 127 characters 11967 Invalid Data You cannot set inventory for more option selections than the number of option selections saved in the button 11968 Invalid Data Option numbers must be unique within an individual button 11969 Invalid Data An option name index value must be specified when tracking inventory or profit amp loss by option 11970 Invalid Argument Option name index value specified is
48. o s browser is redirected after example a URL on your site that ur payment page Default The browser is redirected to a PayPal web page Return method The FORM MI E THOD used to send data to the URL specified by the return variable after payment completion Allowable values e 0 all shopping cart transactions use the GET method e 1 the payer s browser is redirected to the return URL by the GET method and no transaction variables are sent e 2 the payer s browser is redirected to the return URL by the POST method and all transaction variables are also posted The default is 0 NOTE The rm variable take is also set s effect only if the return variable 2 90 1 024 1 Button Manager SOAP API June 2009 65 66 HTML Variables for Website Payments Standard HTML Variables for Prepopulating PayPal Checkout Pages Required or Character Name Optional Description Length cbt Optional Sets the text for the Return to Merchant button on the PayPal 60 Payment Complete page For Business accounts the return button displays your business name in place of the word Merchant by default For Donate buttons the text reads Return to donations coordinator by default NOTE The return variable must also be set cancel Optional A URL to which the payer s browser is redirected if payment is 1 024 return cancelled for example a URL on your website that displays a Paymen
49. on 127 The invoice number will be shown to subscribers with the other details of their transactions modify Optional Modification behavior Allowable values 1 e 0 allows subscribers to only create new subscriptions e 1 allows subscribers to modify their current subscriptions or sign up for new ones e 2 allows subscribers to only modify their current subscriptions The default value is 0 usr manage Optional Set to 1 to have PayPal generate usernames and initial passwords 1 for subscribers 62 June 2009 Button Manager SOAP API HTML Variables for Website Payments Standard EN HTML Variables for Displaying PayPal Checkout Pages HTML Variables for Displaying PayPal Checkout Pages HTML variables for displaying PayPal checkout pages control how the pages appear and function Button Manager SOAP API June 2009 63 HTML Variables for Website Payments Standard HTML Variables for Displaying PayPal Checkout Pages HTML Variables for Displaying PayPal Checkout Pages 64 Required or Character Name Optional Description Length page style Optional The custom payment page style for checkout pages Allowable 30 values e paypal use the PayPal page style e primary use the page style that you marked as primary in your account profile e page style name use the custom payment page style from your account profile that has the specified name The default is primary if you added a custom payment page style to yo
50. os Character length and limitations 63 single byte alphanumeric characters each OptionDetails ns OptionDetailsType Optional Menu items TextBox xs string Optional Text description for a menu item It is a list of variables in which n is a digit between 0 and 1 inclusive ButtonImage ebl ButtonImageType Optional The kind of button image It is one of the following values e REG regular default e SML small e CC small button image with credit card logos not applicable for Unsubscribe or View Cart buttons NOTE Specify either the kind of button image or the URL ButtonImageURL xs string Optional The button s URL NOTE Specify either the kind of button image or the URL BuyNowText ebl BuyNowTextType Optional The button text for a Buy Now button It is one of the following values e BUYNOW button text is Buy Now default e PAYNOW button text is Pay Now SubscribeText ebl SubscribeTextType Optional The button text for a Subscribe button It is one of the following values e BUYNOW button text is Buy Now e SUBSCRIBE button text is Subscribe default Button Manager SOAP API June 2009 27 EI Button Manager API Reference BMUpdateButton API Operation Field Description ButtonCountry ButtonLanguage ebl CountryCodeType Optional The country in which the transaction occurs See Country Codes for a list of country codes By default it is the merchant s country of registration wi
51. ring HTML code for web pages xs string Code for email links and links in other documents that support external links xs string HTML standard button variables which are described in HTML Variables for Website Payments Standard It is a list of variables in which n is a digit between 0 and 9 inclusive Character length and limitations 63 single byte alphanumeric characters each ns OptionDetailsType Menu items xs string Text description for a menu item It is a list of variables in which n is a digit between 0 and 2 inclusive ebl ButtonImageType The kind of button image It is one of the following values e REG regular e SML small e CC credit card logos xs string The button s URL ebl BuyNowTextType The button text for a Buy Now button It is one of the following values e BUYNOW button text is Buy Now e PAYNOW button text is Pay Now ebl SubscribeTextType The button text for a Subscribe button It is one of the following values e BUYNOW button text is Buy Now e SUBSCRIBE button text is Subscribe ebl CountryCodeType The country in which the transaction occurs See Country Codes for a list of country codes By default it is the merchant s country of registration with PayPal xs string The languange in which to display the button text Character length and limitations 2 single byte alphanumeric characters June 2009 Button Manager SOAP API Button Manager API Reference ES BMMan
52. rt or third party SU o me AUGE os Click to check each Button Manager API to which you want to provide access Button Manager SOAP API June 2009 11 12 Website Payments Standard Button Manager API Overview Granting Third Party Permission for APIs 8 Click Submit BMManageButtonStatus BMCreateButton BMUpdateButton BMSetlnventory C BMGetlnventory BMButtonSearch BMGetButtonDetails June 2009 Button Manager SOAP API Using the Button Manager API These examples show basic Button Manager API capabilities The examples show how to create buttons and set inventory levels e Specifying HTML Variables e Creating a Button Using SOAP e Tracking Inventory for a Button Using SOAP Specifying HTML Variables When you create or update a button using the Button Manager API you must specify the same HTML variables that you specify when creating any Website Payments Standard button Although you can use the ButtonVar field to specify any HTML variables some variables are commonly used in specific ways The following table provides additional information about some of these variables HTML Variable Notes item name Name or description of item Must be specified for Add to Cart buttons Character length and limitations 127 single byte alphanumeric characters amount The price or amount of the item Required for Add to Cart buttons May not be used when a dropdown with price L OPTIONOPRICE
53. scription Character Length os0 Optional osl Optional option index See description Option selection of the buyer for the first option field on0 If the option field is a dropdown menu or a set of radio buttons each allowable value should be no more than 64 characters If buyers enter this value in a text field there is a 200 character limit NOTE The option field on0 must also be defined For example it could be size For priced options include the price and currency symbol in the text of the option selections as the following sample code shows lt option value small gt small 10 00 lt option gt Add a corresponding option select0 and option amount0 variable for each priced option Priced options are supported only for Buy Now and Add to Cart buttons Only one dropdown menu option selection can have priced options e Optional for Buy Now Subscribe and Add to Cart buttons e Not used with Donate or Buy Gift Certificate buttons Option selection of the buyer for the second option field onl If the option field is a dropdown menu or a set of radio buttons each allowable value should be no more than 64 characters If buyers enter this value in a text field there is a 200 character limit You can specify a maximum of 7 option selections 6 with Subscribe buttons by incrementing the option selection index os0 through os6 You can implement up to 5 option selections as dropdown menus and up to 2 option sele
54. set the inventory level for a button PayPal can track inventory calculate the gross profit associated with sales send you an alert when inventory drops below a specified quantity and manage sold out conditions e BMsSetInventory Request e BMsSetInventory Response e BMSetInventory Errors BMSetlnventory Request The request specifies inventory values related to a hosted button as well as inventory values that are specific to each menu item associated with the button Button Manager SOAP API June 2009 39 40 Button Manager API Reference BMSetInventory API Operation class ButtonManager eblAbstractRequestType XSDcomplexT ype BMSetinv entoryRequest XSDelements ext ref 1 eblitemT racking Details 0 1 ext ref 2 ebl OptionT rackingDetails 0 10 HosedButioniD xs sting Op onindex xs sting 0 SoldoutURL xs sting 0 Trackinv xs sting TrackPnl xs string class ButtonManagerTypes XSDcom plexT ype Item TrackingDetsilsType XSDelement hemAlen xssmng 0 ItemCos xs string 0 ltemNumber xs sting 0 ItemQty xsstring D IKtemQtyDeita xs sring 0 class ButtonManagerTypes XSDcomplexT ype OptionTrackingDetails Type XSDelements Op onAler xs sting 0 OptionCos xs sting 0 OptonNumber xs sting 0 OptionQty xsstring D Op onQtyDelta xs string 0 OptionSelect xsstring 0 BMSetlnventory Request Fields Field Description HostedButtonID xs string
55. t optionSelectionDetails gt lt com paypal soap api OptionDetailsT om paypal soap api OptionSelectionDetailsType gt lt optionSelection gt ZZZZ lt optionSelection gt com paypal soap api OptionSelectionDetailsType lt optionDetails gt lt but tonImage gt value gt lt m__value gt R lt _ value gt lt buttonImage gt lt buttonImageURL gt lt buttonImageURL gt lt buyNowText gt value gt m value gt bu su yNowText bscribeText value gt m value gt SUBSCRIB value gt su bscribeText gt lt buttonCountry gt value gt m value gt bu bu ttonCountry gt lt com paypal soap api i ype gt EG m value value BUYNOW m value E m value value US m value ttonLanguage gt lt buttonLanguage gt BMCreateButtonRequestType gt Tracking Inventory for a Button Using SOAP The example shows the SOAP parameters that enable tracking of inventory and profit and loss for a button June 2009 Button Manager SOAP API Using the Button Manager API a Tracking Inventory for a Button Using SOAP lt com paypal soap api BMSetInventoryRequestType gt lt hostedButtonID gt 41 lt hostedButtonID gt lt trackInv gt 1 lt trackInv gt lt trackPn1 gt 1 lt trackPn1 gt lt itemTrackingDetails gt lt itemNumber gt 234234 lt itemNumber gt itemQty
56. t Canceled page Default The browser is redirected to a PayPal web page HTML Variables for Prepopulating PayPal Checkout Pages HTML variables for prepopulating PayPal checkout pages let you specify information about the payer HTML Variables for Prepopulating Checkout Pages With Payer Information Required or Character Name Optional Description Length address1 Optional Street 1 of 2 fields 100 address2 Optional Street 2 of 2 fields 100 city Optional City 40 country Optional Sets shipping and billing country 2 first name Optional First name 32 last name Optional Last name 64 lc Optional Sets the payer s language for the billing information log in page 2 only The default is US charset Optional Sets the character encoding for the billing information log in 21 page for the information you send to PayPal in your HTML button code and for the information that PayPal returns to you as a result of checkout processes initiated by the payment button The default is based on the character encoding settings in your account profile night Optional The area code for U S phone numbers or the country code for See phone a phone numbers outside the U S This will prepopulate the payer s description home phone number June 2009 Button Manager SOAP API HTML Variables for Website Payments Standard HTML Variables for Prepopulating PayPal Checkout Pages Required or Character Name Optional Description Le
57. t Item cost value must be specified when tracking profit amp loss by item 11984 Invalid Argument The item cost value specified is invalid 11985 Invalid Argument An item cost value cannot be specified when TrackPnl is 0 11986 Invalid Data The number of option cost values specified is greater than the number of option selections in the saved button 11987 Invalid Argument Option cost values must be specified when tracking profit amp loss by option 11988 Invalid Argument An option cost value specified is invalid 11989 Invalid Argument An option cost value cannot be specified when TrackPnl is 0 11990 Invalid Argument The sold out URL specified is invalid 11992 Invalid Argument You do not have permissions to access this button Please check the hosted button ID and try again BMGetinventory API Operation Use the BMGet Inventory API operation to determine the inventory levels and other inventory related information for a button and menu items associated with the button Typically you call BMGet Inventory to obtain field values before calling BMSet Inventory to change the inventory levels e BMGetInventory Request e BMGetInventory Response e BMGetInventory Errors Button Manager SOAP API June 2009 45 eam Button Manager API Reference BMGetlnventory API Operation BMGetlnventory Request The hosted button ID identifies the button whose inventory you want to track class ButtonMa
58. t Upload command display See Display the contents of the PayPal Shopping Cart to the 1 description buyer This variable must be set as follows display 1 The alternative is the add 1 variable which adds an item to the PayPal Shopping Cart If both add and display are specified display takes precedence Button Manager SOAP API June 2009 59 eun HTML Variables for Website Payments Standard HTML Variables for Subscribe Buttons Required Characte Name or Optional Description r Length handling cart Optional Single handling fee to be charged cart wide If handling cart is used in multiple Add to Cart buttons the handling cart value of the first item is used item name Required Name of the item or a name for the entire Shopping Cart paymentaction Optional Indicates whether the transaction is payment on a final sale or an authorization for a final sale to be captured later Allowable values e sale e authorization e order The default value is sale Set the value to authorization to place a hold on the PayPal account for the authorized amount Set the value to order to authorize the transaction without placing a hold on the PayPal account IMPORTANT If you set paymentaction to order you must use the Authorization amp Capture API to authorize and capture the transaction payments The merchant tools on the PayPal websitel let you capture payments only for authorizations not for orders shopping url Optional
59. t buttons for the PayPal Shopping Cart e upload The Cart Upload command for third party carts S xclick The button that the person clicked was protected from tampering by using encryption or the button was saved in the merchant s PayPal account PayPal determines which kind of button was clicked by decoding the encrypted code or by looking up the saved button in the merchant s account HTML Variables for Special PayPal Features Required or Character Name Optional Description Length notify url Optional The URL to which PayPal posts information about the 255 transaction in the form of Instant Payment Notification messages hosted button Required for The identifier of a button that was saved in a merchant s See id buttons that PayPal account Allowable values are assigned by PayPal description have been when payments buttons are first created and saved saved in PayPal merchants PayPal accounts pide NOTE A merchant s PayPal account can have a maximum DICES not of 1 000 saved payment buttons allowed HTML Variables for Individual Items HTML variables for individual items specify information about a product or service for Buy Now and Add to Cart buttons or they specify information about a contribution for Donate buttons 50 June 2009 Button Manager SOAP API HTML Variables for Website Payments Standard E HTML Variables for Individual Items HTML Variables for Individual Items Required or Character Name Op
60. tate string string city string string zip string lt string gt no_shipping 0 lt string gt lt string gt address override 0 lt string gt lt buttonVar gt lt optionDetails gt lt com paypal soap api OptionDetailsType gt lt optionName gt DD1 lt optionName gt lt optionSelectionDetails gt lt com paypal soap api OptionSelectionDetailsType gt lt optionSelection gt AAAA lt optionSelection gt lt price gt 1 55 lt price gt lt com paypal soap api OptionSelectionDetailsType gt lt com paypal soap api OptionSelectionDetailsType gt lt optionSelection gt BBBB lt optionSelection gt lt price gt 10 55 lt price gt lt com paypal soap api OptionSelectionDetailsType gt lt com paypal soap api OptionSelectionDetailsType gt optionSelection CCCCC optionSelection lt price gt 10 55 lt price gt lt com paypal soap api OptionSelectionDetailsType gt lt optionSelectionDetails gt lt com paypal soap api OptionDetails m ype gt m lt com paypal soap api OptionDetailsType gt Button Manager SOAP API June 2009 15 16 Using the Button Manager API Tracking Inventory for a Button Using SOAP lt optionName gt DD2 lt optionName gt lt optionSelectionDetails gt lt com paypal soap api OptionSelectionDetailsType gt lt optionSelection gt XXXX lt optionSelection gt com paypal soap api OptionSelectionDetailsType lt lt c lt l
61. teButton Response Fields Field Description Website xs string HTML code for web pages Button Manager SOAP API June 2009 23 Button Manager API Reference BMCreateButton API Operation Field Description Email xs string Code for email links and links in other documents that support external links HostedButtonID xs string ID of a PayPal hosted button BMCreateButton Errors 24 Error Code Short Message Long Message Correcting This Error 10001 Internal Error Internal Error 11923 Invalid Argument The button image value specified is invalid 11924 Invalid Argument The button image URL specified is invalid 11925 Invalid Argument The button type specified is invalid 11926 Invalid Data One of the parameters specified using ButtonVar is invalid 11927 Invalid Argument The buy now button text specified is invalid 11928 Invalid Argument The email or merchant ID specified is invalid 11929 Invalid Data A cart button must have an item name and amount specified 11930 Invalid Data A gift certificate button must have a valid shopping URL specified 11931 Invalid Argument The subscription button text specified 1s invalid 11932 Invalid Data You must specify a corresponding number of entries for option names and selections 11933 Invalid Data You cannot skip index numbers for option selections Option selections must be specified sequentially 11934 Invalid Data You must specify the same number of
62. th PayPal xs string Optional The language in which to display the button text It must be compatible with the country code Character length and limitations 2 single byte alphanumeric characters Option Details Fields Field Description OptionName OptionSelectionDetails xs string Optional The menu name ns OptionSelectionDetailsType Menu items OptionSelectionDetails OptionSelection Price xs string Optional The menu item s name xs string Optional The price associated with the first menu item NOTE If you specify a price you cannot set a button variable to amount Button Language Options The button language must be compatible with the country identified by the country code Country Button Language Options All countries not identified below Austria Belgium Canada China worldwide en English default de German default en English en English default nl Dutch fr French en English default fr French en English default zh Chinese 28 June 2009 Button Manager SOAP API Button Manager API Reference BMUpdateButton API Operation Country Button Language Options France e fr French default e en English Germany e de German default e en English Hong Kong e zh Chinese default e en English Italy e it Italian default e en English Japan e ja Japanese default e en English Mexico e
63. tional Description Length amount See The price or amount of the product service or contribution description not including shipping handling or tax If omitted from Buy Now or Donate buttons payers enter their own amount at the time of payment e Required for Add to Cart buttons e Optional for Buy Now and Donate buttons e Not used with Subscribe or Buy Gift Certificate buttons discount amount Optional Discount amount associated with an item It must be less than the selling price of the item If you specify discount amount and discount amount2 is not defined then this flat amount is applied regardless of the quantity of items purchased Valid only for Buy Now and Add to Cart buttons discount amount Optional Discount amount associated with each additional quantity of 2 the item It must be equal to or less than the selling price of the item A discount amount must also be specified as greater than or equal to 0 for discount amount2 to take effect Valid only for Buy Now and Add to Cart buttons discount rate Optional Discount rate percentage associated with an item It must be set to a value less than 100 If you do not set discount rate2 the value in discount rate applies only to the first item regardless of the quantity of items purchased Valid only for Buy Now and Add to Cart buttons discount rate2 Optional Discount rate percentage associated with each additional quantity of the item It must be equal to or less 100 A
64. to specify for the option associated with this menu item Specify either the change in quantity in this field or the absolute quantity in the quantity field xs string Optional The quantity of the option associated with this menu item below which PayPal sends you an email notification xs string Optional The cost of the option associated with this menu item Limitations Value must be a positive number with no currency symbol It must have two decimal places and the decimal separator must be a period It may have an optional comma for the thousands separator BMSetlnventory Response The response consists of a transaction ID June 2009 Button Manager SOAP API Button Manager API Reference ES BMSetInventory API Operation class ButtonManager 26 AbstractResponse Type XSDcom plexT ype BMSetinventoryResponse XSDelemente TransactioniD xsstring BMSetlnventory Response Fields Field Description TransactionID xs string Transaction ID BMSetlnventory Errors Error Code Short Message Long Message Correcting This Error 10001 Internal Error Internal Error 11950 Invalid Data A hosted button ID must be specified 11951 Invalid Argument The hosted button ID specified is invalid 11951 Invalid Argument The hosted button ID specified is invalid 11953 Invalid Data You can only track inventory and profit amp loss for buy now cart or subscription buttons 11954 Invalid Data A TrackI
65. ton SUBSCRIBE Subscribe button DONATE Donate button UNSUBSCRIBE Unsubscribe button VIEWCART View Cart button NOTE You cannot change the kind of button after the button has been created ButtonCode ebl ButtonCodeType Optional The kind of button code to create It is one of the following values e HOSTED A secure button stored on PayPal default for all buttons except View Cart and Unsubscribe e ENCRYPTED An encrypted button not stored on PayPal default for View Cart button e CLEARTEXT An unencrypted button not stored on PayPal default for Unsubscribe button NOTE You cannot change the kind of button code after after the button has been created 26 June 2009 Button Manager SOAP API Button Manager API Reference ES BMUpdateButton API Operation Field Description ButtonSubType ebl ButtonSubTypeType Optional The use of button you want to create It is one ofthe following values e PRODUCTS button is used to purchase products default for Buy Now and Add to Cart buttons e SERVICES button is used to purchase services NOTE You cannot change the button usage after after the button has been created ButtonVar xs string Optional HTML standard button variables which are described in HTML Variables for Website Payments Standard It is a list of variables in which n is a digit between 0 and 999 inclusive do not include leading zer
66. ur account profile Otherwise the default is paypal image url Optional The URL ofthe 150x50 pixel image displayed as your logo in the 1 024 upper left corner of the PayPal checkout pages Default Your business name if you have a Business account or your email address if you have Premier or Personal account cpp header Optional The image at the top left of the checkout page The image s No limit image maximum size is 750 pixels wide by 90 pixels high PayPal recommends that you provide an image that is stored only on a secure https server cpp Optional The background color for the header of the checkout page 6 headerback_ Valid value is case insensitive six character HTML hexadecimal color color code in ASCII cpp Optional The border color around the header of the checkout page The 6 headerborder border is a 2 pixel perimeter around the header space which has color a maximum size of 750 pixels wide by 90 pixels high Valid value is case insensitive six character HTML hexadecimal color code in ASCII cpp payflow Optional The background color for the checkout page below the header 6 color Valid value is case insensitive six character HTML hexadecimal color code in ASCII NOTE Background colors that conflict with PayPal s error messages are not allowed in these cases the default color is white cs Optional The background color of the checkout page Allowable values 1 e 0 background color is white e 1 background color is blac

PayPal Website Payments Standard - 2009 - Button Manager API (SOAP) User Guide

Contents

Download Pdf Manuals

Related Search

Related Contents