Website Payments Standard Button Manager API (NVP) For Professional Use Only Currently only available in English. A usage Professional Uniquement Disponible en Anglais uniquement pour l’instant.
Button Manager NVP API Document Number: 10089.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 BMGetButtonDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 BMGetButtonDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 BMGetButtonDetails Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 BMManageButtonStatus API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 BMManageButtonStatus Request . . . . . . . . .
Preface This document describes the Button Manager API for NVP. 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 (NVP). 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 NVP 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 NVP z Tracking Inventory for Menu Items Using NVP 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 NVP 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 Tracking Inventory for Menu Items Using NVP ... &BUTTONCODE=HOSTED &BUTTONTYPE=CART &L_BUTTONVAR0=business=merchant@abc.com &L_BUTTONVAR1=item_name=Wireless%20Mouse &L_BUTTONVAR2=amount=10.50 &L_BUTTONVAR3=no_shipping=1 &L_BUTTONVAR4=currency_code=USD &L_BUTTONVAR5=no_note=1 &OPTION0NAME=Color &L_OPTION0SELECT0=Red &L_OPTION0SELECT1=Blue &L_OPTION0SELECT2=Green &L_OPTION0PRICE0=10.00 &L_OPTION0PRICE1=8.00 &L_OPTION0PRICE2=12.
Using the Button Manager API Tracking Inventory for Menu Items Using NVP ... &TRACKINV=1 &TRACKPNL=1 &OPTIONINDEX=0 &L_OPTIONNUMBER0=1001 &L_OPTIONQTY0=100 &L_OPTIONALERT0=5 &L_OPTIONCOST0=4.50 &L_OPTIONNUMBER1=1002 &L_OPTIONQTY1=200 &L_OPTIONALERT1=5 &L_OPTIONCOST1=5.50 &L_OPTIONNUMBER2=1003 &L_OPTIONQTY2=150 &L_OPTIONALERT2=5 &L_OPTIONCOST2=5.00 &SOLDOUTURL=http://mysoldoutpage.
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 Field Description BUTTONCODE (Optional) The kind of button code to create. It is one of the following values: z HOSTED - A secure button stored on PayPal; default for all buttons except View Cart and Unsubscribe z ENCRYPTED - An encrypted button, not stored on PayPal; default for View Cart button z CLEARTEXT - An unencrypted button, not stored on PayPal; default for Unsubscribe button BUTTONTYPE (Required) The kind of button you want to create.
Button Manager API Reference BMCreateButton API Operation Field Description BUYNOWTEXT (Optional) The button text for a Buy Now button. It is one of the following values: z BUYNOW - button text is Buy Now; default z PAYNOW - button text is Pay Now SUBSCRIBETEXT (Optional) The button text for a Subscribe button. It is one of the following values: z BUYNOW - button text is Buy Now z SUBSCRIBE - button text is Subscribe; default BUTTONCOUNTRY (Optional) The country in which the transaction occurs.
Button Manager API Reference BMCreateButton API Operation Country Button Language Options Belgium z z z Canada z z China (worldwide) z z 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 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; def
Button Manager API Reference BMCreateButton API Operation BMCreateButton Response Fields Field Description WEBSITECODE HTML code for web pages EMAILLINK Code for email links and links in other documents that support external links HOSTEDBUTTONID ID of a PayPal-hosted button BMCreateButton Errors 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 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.
Button Manager API Reference BMUpdateButton API Operation BMUpdateButton Request The hosted button ID identifies the button you want to modify. The remaining request fields specify the characteristics of your button. BMUpdateButton Request Fields Field Description METHOD (Required) BMUpdateButton HOSTEDBUTTONID (Required) The ID of the hosted button you want to modify. BUTTONTYPE (Required) The kind of button you want to update.
Button Manager API Reference BMUpdateButton API Operation Field Description L_TEXTBOXn 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 (Optional) The kind of button image.
Button Manager API Reference BMUpdateButton API Operation L_OPTIONnSELECTx (Optional) The menu item’s name It is a list of variables for each OPTIONnNAME, in which x is a digit between 0 and 9, inclusive. L_OPTION0PRICEx (Optional) The price associated with the first menu item It is a list of variables for each OPTION0NAME, in which x is a digit between 0 and 9, inclusive. NOTE: If you specify a price, you cannot set a button variable to amount.
Button Manager API Reference BMUpdateButton API Operation Country Button Language Options Poland z z Spain z z Switzerland z z z United States z z z z 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 BMUpdateButton Response The response contains the hosted button ID, code for HTML in a website, and code for a link in email.
Button Manager API Reference BMUpdateButton API Operation Error Code Short Message Long Message 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 is invalid.
Button Manager API Reference BMButtonSearch API Operation Error Code Short Message Long Message 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. Correcting This Error...
Button Manager API Reference BMGetButtonDetails API Operation L_HOSTEDBUTTONIDn The hosted button ID It is a list of variables, in which n is a digit between 0 and 9, inclusive. L_BUTTONTYPEn The hosted button ID It is a list of variables, in which n is a digit between 0 and 9, inclusive. L_ITEMNAMEn The item name It is a list of variables, in which n is a digit between 0 and 9, inclusive.
Button Manager API Reference BMGetButtonDetails API Operation BMGetButtonDetails Request Fields Field Description METHOD (Required) BMGetButtonDetails HOSTEDBUTTONID (Required) The ID of the hosted button whose details you want to obtain. BMGetButtonDetails Response The response fields contain all non-inventory information related to the button. BMGetButtonDetails Response Fields 30 Field Description BUTTONTYPE The kind of button.
Button Manager API Reference BMGetButtonDetails API Operation Field Description BUTTONIMAGE The kind of button image. It is one of the following values: z REG - regular z SML - small z CC - credit card logos BUTTONIMAGEURL xs:string The button’s URL BUYNOWTEXT The button text for a Buy Now button. It is one of the following values: z BUYNOW - button text is Buy Now z PAYNOW - button text is Pay Now SUBSCRIBETEXT The button text for a Subscribe button.
Button Manager API Reference BMManageButtonStatus API Operation L_OPTIONnSELECTx (Optional) The menu item’s name It is a list of variables for each OPTIONnNAME, in which x is a digit between 0 and 9, inclusive. L_OPTION0PRICEx (Optional) The price associated with the first menu item It is a list of variables for each OPTION0NAME, in which x is a digit between 0 and 9, inclusive. NOTE: If you specify a price, you cannot set a button variable to amount.
Button Manager API Reference BMSetInventory API Operation BMManageButtonStatus Request Fields Field Description METHOD (Required) BMManageButtonStatus HOSTEDBUTTONID (Required) The ID of the hosted button whose status you want to change. BUTTONSTATUS (Required) The new status of the button. It is one of the following values: z DELETE - the button is deleted from PayPal BMManageButtonStatus Response The response does not include any fields that are specific to the BMManageButtonStatus API operation.
Button Manager API Reference BMSetInventory API Operation BMSetInventory 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. BMSetInventory Request Fields Field Description METHOD (Required) BMSetInventory HOSTEDBUTTONID (Required) The ID of the hosted button whose inventory you want to set. TRACKINV (Required) Whether to track inventory levels associated with the button.
Button Manager API Reference BMSetInventory API Operation ITEMALERT (Optional) The quantity of the item associated with this button below which PayPal sends you an email notification ITEMCOST (Optional) The cost of the item associated with this button Option Tracking Details Fields L_OPTIONNUMBERn (Optional) The menu item’s ID for an option in a dropdown menu It is a list of variables for each menu item, in which n is a digit between 0 and 9, inclusive.
Button Manager API Reference BMSetInventory API Operation BMSetInventory Errors 36 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. 11953 Invalid Data You can only track inventory and profit & loss for buy now, cart or subscription buttons.
Button Manager API Reference BMSetInventory API Operation Error Code Short Message Long Message 11969 Invalid Data An option name index value must be specified when tracking inventory or profit & loss by option. 11970 Invalid Argument Option name index value specified is invalid. 11971 Invalid Data Inventory and/or profit & 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.
Button Manager API Reference BMGetInventory API Operation Error Code Short Message Long Message 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 & loss by option. 11988 Invalid Argument An option cost value specified is invalid.
Button Manager API Reference BMGetInventory API Operation BMGetInventory Response The response fields contain inventory information related to the button. BMGetInventory Response Fields Field Description HOSTEDBUTTONID The ID of the hosted button whose inventory you want to set. TRACKINV Whether to track inventory levels associated with the button.
Button Manager API Reference BMGetInventory API Operation Option Tracking Details Fields L_OPTIONNUMBERn The menu item’s ID for an option in a dropdown menu It is a list of variables for each menu item, in which n is a digit between 0 and 9, inclusive. L_OPTIONQTYn The current inventory level of the option associated with this menu item It is a list of variables for each menu item, in which n is a digit between 0 and 9, inclusive.
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 49
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 60 June, 2009 Button Manager NVP API
