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.
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.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Chapter 1 Website Payments Standard Button Manager API Overview 7 Button Manager Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Generated Button Code . . . . . . . . . . . . . . . . . . .
Contents BMGetButtonDetails API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 BMGetButtonDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 BMGetButtonDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 BMGetButtonDetails Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 BMManageButtonStatus API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 BMManageButtonStatus Request . . . . . . . . .
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 Manager 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.
Revision History 6 June, 2009 Button Manager SOAP API
1 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.
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.
Website Payments Standard Button Manager API Overview Button Hosting
Website Payments Standard Button Manager API Overview Hosted Button Manipulation z 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. z Encrypted buttons are not stored on PayPal.
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 sold 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.
Website Payments Standard Button Manager API Overview Granting Third-Party Permission for APIs 8. Click Submit.
2 Using the Button Manager API These examples show basic Button Manager API capabilities. The examples show how to create buttons and set inventory levels. z Specifying HTML Variables z Creating a Button Using SOAP z 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.
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.
Using the Button Manager API Creating a Button Using SOAP <__value__> CART <__value__> HOSTED <__value__> PRODUCTS business=XX-usbiz@paypal.com item_name=Item-123 item_number=#1234 shipping=0.
Using the Button Manager API Tracking Inventory for a Button Using SOAP DD2 XXXX ZZZZ
Using the Button Manager API Tracking Inventory for a Button Using SOAP 41 1 1 234234 10 2 4 http://www.paypal.com
Using the Button Manager API Tracking Inventory for a Button Using SOAP 18 June, 2009 Button Manager SOAP API
3 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.
Button Manager API Reference BMCreateButton API Operation BMCreateButton Request Fields 20 Field Description ButtonCode ebl:ButtonCodeType (Optional) The kind of button code to create.
Button Manager API Reference BMCreateButton API Operation Field Description 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 zeros.
Button Manager API Reference BMCreateButton 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.
Button Manager API Reference BMCreateButton API Operation Country Button Language Options Japan z z Mexico z z Netherlands z z Poland z z Spain z z Switzerland z z z United States z z z z ja - Japanese; default en - English es - Spanish; default en - English nl - Dutch; default en - English pl - Polish; default en - English es - Spanish; default en - English de - German; default fr - French en - English en - English; default fr - French es - Spanish zh - Chinese BMCreateButton Response The
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 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.
Button Manager API Reference BMUpdateButton API Operation Error Code Short Message Long Message 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.
Button Manager API Reference BMUpdateButton API Operation 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.
Button Manager API Reference BMUpdateButton API Operation Field Description ButtonSubType ebl:ButtonSubTypeType (Optional) The use of button you want to create. It is one of the following values: z PRODUCTS - button is used to purchase products; default for Buy Now and Add to Cart buttons z SERVICES - button is used to purchase services NOTE: You cannot change the button usage after after the button has been created.
Button Manager API Reference BMUpdateButton API Operation Field Description 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.
Button Manager API Reference BMUpdateButton API Operation Country Button Language Options France z z Germany z z Hong Kong z z Italy z z Japan z z Mexico z z Netherlands z z Poland z z Spain z z Switzerland z z z United States z z z z fr - French; default en - English de - German; default en - English zh - Chinese; default en - English it - Italian; default en - English ja - Japanese; default en - English es - Spanish; default en - English nl - Dutch; default en - English pl - Polis
Button Manager API Reference BMUpdateButton API Operation BMUpdateButton Response Fields Field Description Website xs:string HTML code for web pages 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 BMUpdateButton Errors 30 Error Code Short Message Long Message 10001 Internal Error Internal Error 11923 Invalid Argument The button image value specified is invalid.
Button Manager API Reference BMUpdateButton API Operation Error Code Short Message Long Message 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.
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. z BMButtonSearch Request z BMButtonSearch Response z BMButtonSearch Errors BMButtonSearch Request The request contains optional fields that are not currently used. All hosted buttons are automatically requested.
Button Manager API Reference BMButtonSearch API Operation 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 10001 Internal Error Internal Error Button Manager SOAP API June, 2009 Correcting This E
Button Manager API Reference BMGetButtonDetails API Operation Error Code Short Message Long Message 11994 Search Warning You have exceeded the maximum number of buttons that can be returned. Please adjust your seach parameters if required. 11997 Invalid Argument A start date value must be specified. 11998 Invalid Argument The start date specified is invalid. 11999 Invalid Argument The end date specified is invalid. Correcting This Error...
Button Manager API Reference BMGetButtonDetails API Operation BMGetButtonDetails Response Fields Field Description ButtonType ebl:ButtonTypeType The kind of button. It is one of the following values: z BUYNOW - Buy Now button z CART - Add to Cart button z GIFTCERTIFICATE - Gift Certificate button z SUBSCRIBE - Subscribe button z DONATE - Donate button z UNSUBSCRIBE - Unsubscribe button z VIEWCART - View Cart button ButtonCode ebl:ButtonCodeType The kind of button code.
Button Manager API Reference BMGetButtonDetails API Operation 36 Field Description Website xs:string HTML code for web pages Email xs:string Code for email links and links in other documents that support external links ButtonVar 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.
Button Manager API Reference BMManageButtonStatus 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.
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. 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.
Button Manager API Reference BMSetInventory API Operation Error Code Short Message Long Message 11993 Invalid Argument The button status value specified is not valid. Correcting This Error... BMSetInventory API Operation Use the BMSetInventory API operation to set the inventory level and inventory management features for the specified button.
Button Manager API Reference BMSetInventory API Operation BMSetInventory Request Fields 40 Field Description HostedButtonID xs:string (Required) The ID of the hosted button whose inventory you want to set.
Button Manager API Reference 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: z 0 - do not track inventory z 1 - track inventory TrackPnl xs:string (Required) Whether to track the gross profit associated with inventory changes.
Button Manager API Reference BMSetInventory API Operation ItemQtyDelta xs:string The change in quantity you want to specify for the item associated with this button.
Button Manager API Reference BMSetInventory API Operation BMSetInventory Response Fields Field Description TransactionID xs:string Transaction ID BMSetInventory Errors Error Code Short Message Long Message 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.
Button Manager API Reference BMSetInventory API Operation 44 Error Code Short Message Long Message 11964 Invalid Data You must either track inventory and/or track profit & 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.
Button Manager API Reference BMGetInventory API Operation Error Code Short Message Long Message 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.
Button Manager API Reference BMGetInventory API Operation BMGetInventory Request The hosted button ID identifies the button whose inventory you want to track. BMGetInventory Request Fields Field Description HostedButtonID xs:string (Required) The ID of the hosted button whose inventory information you want to obtain. BMGetInventory Response The response fields contain inventory information related to the button.
Button Manager API Reference BMGetInventory API Operation Field Description TrackInv xs:string Whether to track inventory levels associated with the button. It is one of the following values: z 0 - do not track inventory z 1 - track inventory TrackPnl xs:string Whether to track the gross profit associated with inventory changes.
Button Manager API Reference BMGetInventory API Operation ItemCost xs:string The cost of the item associated with this button Option Tracking Details Fields OptionNumber xs:string The 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 ite
A 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.
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.
HTML Variables for Website Payments Standard HTML Variables for Individual Items HTML Variables for Individual Items Name Required or Optional Description amount See description. The price or amount of the product, service, or contribution, not including shipping, handling, or tax. If omitted from Buy Now or Donate buttons, payers enter their own amount at the time of payment.
HTML Variables for Website Payments Standard HTML Variables for Individual Items Name Required or Optional item_name See description. Description of item. If omitted, payers enter their own name at the time of payment. z Optional for Buy Now, Donate, Subscribe and Add to Cart buttons z Not used with Buy Gift Certificate buttons 127 item_number Optional Pass-through variable for you to track product or service purchased or the contribution made.
HTML Variables for Website Payments Standard HTML Variables for Individual Items Name Required or Optional Description undefined_ quantity Optional 1 – allows buyers to specify the quantity. z Optional for Buy Now buttons z 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.
HTML Variables for Website Payments Standard HTML Variables for Individual Items Name Required or Optional os0 Optional Character Length 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: 64 or 200 See description. The option field on0 must also be defined.
HTML Variables for Website Payments Standard HTML Variables for Individual Items Name Required or Optional option_select0 Optional Description For priced options, the value of the first option selection of the on0 dropdown menu. The values must match exactly, as the next sample code shows: Character Length 64 small - $10.00 ...
HTML Variables for Website Payments Standard HTML Variables for Payment Transactions Name Required or Optional option_amount1 Optional Character Length Description For priced options, the amount that you want to charge for the second option selection of the on0 dropdown menu. For example: 64 ... medium - $15.00 ... PAGE 57
HTML Variables for Website Payments Standard HTML Variables for Payment Transactions HTML Variables for Payment Transactions Name Required or Optional Character Length Description address_ override Optional 1 – The address specified in prepopulation variables overrides the 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.
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.
HTML Variables for Website Payments Standard HTML Variables for Shopping Carts HTMLVariables for Shopping Carts Name add Required or Optional Description Characte r Length See description 1 Add an item to the PayPal Shopping Cart. 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.
HTML Variables for Website Payments Standard HTML Variables for Subscribe Buttons Name Required or Optional Description Characte 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.
HTML Variables for Website Payments Standard HTML Variables for Subscribe Buttons HTML Variables for Subscribe Buttons Name Required or Optional 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.
HTML Variables for Website Payments Standard HTML Variables for Subscribe Buttons Name Required or Optional src Optional Character Length Description Recurring payments. Subscription payments recur unless 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: z 0 – subscription payments do not recur z 1 – subscription payments recur 1 The default is 0.
HTML Variables for Website Payments Standard 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.
HTML Variables for Website Payments Standard HTML Variables for Displaying PayPal Checkout Pages HTML Variables for Displaying PayPal Checkout Pages Name Required or Optional page_style Optional Character Length Description The custom payment page style for checkout pages.
HTML Variables for Website Payments Standard HTML Variables for Displaying PayPal Checkout Pages Name Required or Optional lc 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 cookie, the default language is U.S. English. For allowable values, see . 2 no_note Optional Do not prompt payers to include a note with their payments.
HTML Variables for Website Payments Standard HTML Variables for Prepopulating PayPal Checkout Pages Name Required or Optional cbt Optional Sets the text for the Return to Merchant button on the PayPal 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.
HTML Variables for Website Payments Standard HTML Variables for Prepopulating PayPal Checkout Pages Name Required or Optional Character Length Description night_ phone_b Optional The three-digit prefix for U.S. phone numbers, or the entire phone number for phone numbers outside the U.S., excluding country code. This will prepopulate the payer’s home phone number. See description. night_ phone_c Optional The four-digit phone number for U.S. phone numbers.
HTML Variables for Website Payments Standard HTML Variables for Prepopulating PayPal Checkout Pages 68 June, 2009 Button Manager SOAP API
