Home

PayPal Website Payments Standard - 2012 - Button Manager API (NVP) User Guide

1. TONVAR33 showBillingPhone true TONVAR34 showCustomerName t rue TONVAR35 showCardInfo true TTONVAR3 6 showHostedThankyouPage true PTONVAR37 bn GBD ma TTONVAR38 cbt Merchant ABCD April 2012 Button Manager NVP API Using the Button Manager API With NVP E Using the Button Manager API With Hosted Solution Checkout L_BU L_BU R60 template templateC R61 return http www martwall com gt L BUTTONVAR39 address override 0 BUTTONVAR40 cpp header image Red L BUTTONVAR41 logoText MartWall BUTTONVAR42 logoImage http i2 martwallimages com wmlogo gif BUTTONVAR43 logoImagePosition center BUTTONVAR44 logoFont Arial Bold L BUTTONVAR45 logoFontSize 24px L BUTTONVAR4 6 logoFontColor f0ff0f BUTTONVAR47 bodyBgImg sdf BUTTONVAR4 8 bodyBgColor AEAEAE L BUTTONVAR4 9 headerHeight 70px L BUTTONVAR5S0 headerBgColor 4B6BA1 L BUTTONVAR51 PageTitleTextColor Blue L BUTTONVAR52 PageCollapseBgColor Blue L BUTTONVAR53 PageCollapseTextColor Yellow L BUTTONVAR54 PageButtonBgColor Blue L BUTTONVAR55 PageButtonFgColor White L_BUTTONVAR5 6 orderSummaryBgColor EDF2F7 L_BUTTONVAR57 orderSummaryBgImage http scr_hss_bg_ordersummary jpg L_BUTTONVAR5 8 footerTextColor 333333 L_BUTTONVARS5 9 footerTextlinkColor 00f00f NVAI NVAI O The res
2. e 27 BMUpdateButton API Operation o e o o oea 29 BMUpdateButton Request o 29 April 2012 EN Contents BMUpdateButton Response 00022 eee ee ee 33 BMUpdateButton Errors 2 2 a 34 BMButtonSearch API Operation e 35 BMButtonSearch Request A 36 BMButtonSearch Response e 36 BMButtonSearch Errors gt sass rsads iadaaa RRR KRK 37 BMGetButtonDetails API Operation 0 a 37 BMGetButtonDetails Request o oo a A 37 BMGetButtonDetails Response ooo a a 38 BMGetButtonDetails Errors a aoao a 40 BMManageButtonStatus API Operation a oa oea a e 2 40 BMManageButtonStatus Request A 41 BMManageButtonStatus Response A 41 BMManageButtonStatus Errors A 41 BMSetlnventory API Operation A 41 BMSetlnventory Request aaa oaa a 42 BMSetlnventory Response a 44 BMSetlnventory Errors aoa oa ee 44 BMGetlnventory API Operation 2 2 47 BMGetlnventory Request aoaaa a 47 BMGetinventory Response 2 2 0 ee 47 BMGetlnventory Errors 2 e 49 Appendix A HTML Variables for PayPal Payments Standard 51 Technical HTML Variables aaau aaa a 51 HTML Variables for Individual Items o ee e e 53 HTML Variables for Payment Transactions 0 a 58 H
3. Creating a Button Using NVP The example shows the NVP parameters for creating a hosted Add to Cart button of the standard size The button is also associated with menu items BUTTONCODE HOSTED BUTTONTYPE CAR L_BUTTONVARO business merchant abc com LB NVAR1 item_name Wireless 20Mouse LB NVAR2 amount 10 50 NVAR3 no_shipping 1 NVAR4 currency_code USD NVAR5 no_note 1 ONONAME Color TONOSELECTO Red L_OPTIONOSEL 1 Blue L_OPTIONOSELECT2 Green L_OPTIONOPRICE0 10 00 L OPTIONOPRICE1 8 00 L OPTIONOPRICE2 12 00 O O O O LC LU T HGGG G G O l QQ OOO 16 April 2012 Button Manager NVP API Using the Button Manager API With NVP Offering Multiple Payment Option Subscriptions Using NVP OPTIONINAME Size L OPTIONISELECTO Small L_OPTION1SELECT1 Large BUTTONIMAGE reg T T The button includes menus that allow you to specify the color and size Each color is associated with a specific price The button variables L_BUTTONVARO and such enable you to specify the same HTML variables as you ordinarily do using PayPal Payments Standard Offering Multiple Payment Option Subscriptions Using NVP The example shows how to create a Subscribe button for 3 kinds of payment options BUTTONTYPE value SUBSCRIBE OPTIONONAME value Special TV L OPTIONOSELECTO value Regular L_OPTIONOPRICEO valu
4. and 4 inclusive Optional The base amount to bill for the cy cle It is a list of variables for each OPTIONONAME in which x is a digit between 0 and 4 inclusive Button Manager NVP API April 2012 39 El Button Manager API Reference BMManageButtonStatus API Operation Field Description IL OPTIONNSHIPPINGAMOUNTx Optional The shipping amount to bill for the cycle in addition to the base amount It is a list of variables for each OPTIONONAME in which x is a digit between 0 and 4 inclusive L_OPTIONNTAXAMOUNTX Optional The tax amount to bill for the cycle in addition to the base amount It is a list of variables for each OPTIONONAME in which x is a digit between 0 and 4 inclusive BMGetButtonDetails Errors ae 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 40 April 2012
5. Substitute lt Country gt with an appropriate two letter country code from codes defined by the ISO 3166 1 standard For example a Buy Now button on your website that you coded yourself might have the following line of code bn DesignerFotos BuyNow WPS US NOTE HTML button code that you create on the PayPal website includes bn variables with valid values generated by PayPal 52 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard oa HTML Variables for Individual Items HTML Variables for Individual ltems 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 HTML Variables for Individual Items Required or Character Name Optional Description Length amount See The price or amount of the product service or contribution description not including shipping handling or tax If this variable is omitted from Buy Now or Donate buttons buyers 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
6. Name Optional Description Length cpp_ Optional The background color for the header of the checkout page 6 headerback_ Valid value is case insensitive six character HTML color hexadecimal color code in ASCII Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command cpp_ Optional The border color around the header of the checkout page 6 headerborder_co The border is a 2 pixel perimeter around the header space lor which has a maximum size of 750 pixels wide by 90 pixels high Valid value is case insensitive six character HTML hexadecimal color code in ASCII Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command cpp logo image Optional A URL to your logo image Use a valid graphics format 127 such as gif jpg or png Limit the image to 190 pixels wide by 60 pixels high PayPal crops images that are larger PayPal places your logo image at the top of the cart review area NOTE PayPal recommends that you store the image on a secure https server Otherwise web browsers display a message that checkout pages contain non secure items Valid value is 127 single byte alphanumeric characters e Valid only for Buy Now and Add to Cart buttons and the Cart Upload command e Not used with Subscribe Donate or Buy Gift Certificate buttons cpp payflow_ Optional The background color for the checkout page below the 6 color header Valid value is case insensitive six character HTML he
7. Buttons that you can view on the My Saved Buttons page of your PayPal profile are called hosted buttons 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 NOTE You cannot use hosted buttons with Hosted Sole Solution you should use token buttons instead 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 regard 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 use an encrypted button only 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 be altered or stolen Token buttons are not stored on PayPal They are only used with Hosted Solution and the parameters associated with this kind of button are secure Token buttons are dynamic and i
8. UNSUBSCRIBE Unsubscribe button e VIEWCART View Cart button e PAYMENTPLAN Installment Plan button since version 63 0 e AUTOBILLING Automatic Billing button since version 63 0 NOTE You cannot change the kind of button after the button has been created BUTTONCODE 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 BUTTONSUBTYPE Optional The use of button you want to create It is one of the following L_BUTTONVARN 1 TEXTBOXN BUTTONIMAGE 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 Optional HTML standard button variables It is a list of variables in which n is a digit between O and 999 inclusive do not include leading zeros Character length and limitations 63 single byte alphanumeric characters each xs string Optional Text description for a menu item It is a list of variables in which n is a digit between O and 1 in
9. absolute quantity in this field or the change in quantity in the quantity delta field ITEMOTYDELTA 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 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 O and 9 inclusive L OPTIONQTYN 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 It is a list of variables for each menu item in which n is a digit between O and 9 inclusive L_OPTIONSELECTn Optional The menu item s name 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 NVP API April 2012 43 4 Button Manager API Reference BMSetInventory API Operation L_OPTIONQTYDELTAn The change in quantity you want to specify for the option associated with this menu item Specify either the change in quantity in this field o
10. both add and display are specified display takes precedence 60 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard A HTML Variables for Recurring Payments Buttons Required or Character Name Optional Description Length handling cart Optional Single handling fee 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 x Required The name associated with item x To pass an aggregate name for the entire cart use item name 1 Applies only to the Cart Upload command paymentaction Optional Indicates whether the payment is a final sale or an authorization for a final sale to be captured later Allowable values are 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 payment without placing a hold on the PayPal account IMPORTANT Ifyou set paymentaction to order use the Authorization amp Capture API to authorize and capture the payment payments The Merchant Services on the PayPal website let you capture payments only for authorizations not for orders shopping url Optional The URL of the page on the merchant website that buyers go to when they click the Continue Shopping button on the PayPal Shopping Cart page upload See Upload the contents of a third party shopp
11. e page style name use the custom payment page style from your account profile that has the specified name The defaultis primary if you added a custom payment page style to your account profile Otherwise the default is paypal image url Optional The URL of the 150x50 pixel image displayed as your logo 1 024 in the upper left corner of the PayPal checkout pages Default Your business name if you have a PayPal Business account or your email address if you have PayPal Premier or Personal account cpp cart border Optional The HTML hex code for your principal identifying color 6 color PayPal blends your color to white in a gradient fill that borders the cart review area of the PayPal checkout user interface Valid value is 6 single byte hexadecimal characters that represent an HTML hex code for a color e Valid only for Buy Now and Add to Cart buttons and the Cart Upload command e Not used with Subscribe Donate or Buy Gift Certificate buttons 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 Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command Button Manager NVP API April 2012 67 A HTML Variables for PayPal Payments Standard HTML Variables for Displaying PayPal Checkout Pages Required or Character
12. is 2 and the billing period is Month the billing cycle is every 2 months The default billing frequency is 1 It is a list of variables for each OPTIONNNAI and 4 inclusive E in which x is a digit between 0 Optional The total number of billing cycles regardless of the duration of a cycle 1 is the default It is a list of variables for each OPTIONNNAI and 4 inclusive E in which x is a digit between 0 Optional The base amount to bill for the cycle It is a list of variables for each OPTIONONAME in which x is a digit between 0 and 4 inclusive Optional The shipping amount to bill for the cycle in addition to the base amount It is a list of variables for each OPTIONONAME in which x is a digit between 0 and 4 inclusive Optional The tax amount to bill for the cycle in addition to the base amount It is a list of variables for each OPTIONONAME in which x is a digit between 0 and 4 inclusive 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 e en English default e de German default e en English e en English default e nl Dutch e fr French April 2012 Button Manager NVP API Button Manager API Reference BMUpdateButton API Operation Country Button Language Options Canada e en Englis
13. not specify PAYMENT if BUTTONCODE HOSTED BUTTONSUBTYP Ea values eo P Optional The use of button you want to create It is one of the following RODUCTS button is used to purchase products default for Buy Now and Add to Cart buttons es ERVIC ES button is used to purchase services L_BUTTONVARN Optional HTML standard button variables Option Details Fields Field Description OPTIONNNAME Optional The menu name It is one or more variables in which n is a digit between O and 4 inclusive for hosted buttons otherwise it is a digit between O and 9 inclusive 24 April 2012 Button Manager NVP API Button Manager API Reference E BMCreateButton API Operation Option Selection Details Fields 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_OPTIONOPRICEX Optional The price associated with the first menu item It is a list of variables for each OPTIONONAME 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 OPTIONNTYP Optional The installment option type for an OPTIONNNAME which is one of the following values e FULL Payment in full e VARIABLE Variable installments e EMI Equal installments Gl NOTE Only available fo
14. number of time pm units with option_selectn_tm If the value of option selectn type is E the value of this variable applies to all payments in the plan option_selectn_ Required Units of time for payment period m 1 tm Allowable values are e D for days allowable range for p3 is 1 to 90 e W for weeks allowable range for p3 is 1 to 52 e M for months allowable range for p3 is 1 to 24 e Y for years allowable range for p3 is 1 to 5 option selectn Required Number of payments that are the same in amount and 1 nm duration as this one e If the value of option selectn type is F set the value to 1 e If the value of option selectn type is E set the value to the number of payments in the plan e If the value of option_selectn_type is F and no subsequent payments are the same as this one set the value to 1 66 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard oa 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 Displaying PayPal Checkout Pages Required or Character Name Optional Description Length page_style Optional The custom payment page style for checkout pages 30 Allowable values are e paypal use the PayPal page style e primary use the page style that you marked as primary in your account profile
15. 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 O 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 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 Button Manager NVP API April 2012 53 A HTML Variables for PayPal Payments Standard HTML Variables for Individual Items Name Required or Optional Description Character Length discount num item name item number quantity shipping shipping2 Optional See description See description Optional Optional Optional Number of additional quantities of the item to which the discount applies Applicable when you
16. range for p3 is 1 to 24 e Y for years allowable range for p3 is 1 to 5 src Optional Recurring payments Subscription payments reoccur 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 are 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 2 payments recur Specify an integer above 1 Valid only if you specify src 1 sra Optional Reattempt on failure If a recurring payment for a legacy 1 subscription fails in which the subscription ID starts with S PayPal attempts to collect the payment two more times before canceling the subscription otherwise when the subscription ID starts with 1 the profile is suspended after the attempt instead of cancelled Allowable values are e 0 do not reattempt failed recurring payments e 1 reattempt failed recurring payments before canceling or suspending The default is 1 no_note Required Do not prompt buyers to include a note with their payments 1 Allowable values for Subscribe buttons e hide the text box and the prompt For Subscribe buttons always include no_note set to 1 custom Optional User defined field which PayPal passes through the system 255 and returns to you in your merchant payment notification email Su
17. the units of duration that you specify with t1 El See Trial period 1 units of duration Required if you specify al 1 description Allowable values are 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 a2 Optional Trial period 2 price Can be specified only if you also specify al p2 See Trial period 2 duration Required if you specify a2 Specify 2 description an integer value in the allowable range for the units of duration that you specify with t2 t2 See Trial period 2 units of duration 1 description Allowable values are 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 2 allowable range for the units of duration that you specify with t3 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard AT HTML Variables for Recurring Payments Buttons Required or Character Name Optional Description Length t3 Required Regular subscription units of duration 1 Allowable values are e D for days allowable range for p3 is 1 to 90 e W for weeks allowable range for p3 is 1 to 52 e M for months allowable
18. 7 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 BMGetButtonDetails API Operation Use the BMGetButtonDetails API operation to obtain information about a hosted PayPal 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 includes only the ID of the hosted button whose details you want to obtain BMGetButtonDetails Request Fields Field Description METHOD Required BMGetButtonDetails HOSTEDBUTTONID Required The ID of the hosted button whose details you want to obtain Button Manager NVP API April 2012 37 38 Button Manager API Reference BMGetButtonDetails API Operation BMGetButtonDetails Response The response fields contain all non inventory information related to the button BMGetButtonDetails Response Fields Field Description BUTTONTYP BUTTONCOD BUTTONSUBTYP VEBSI E E HOSTEDBUTTONID ECODE EMAT LINK 1 BUTTONVAI RN E The kind of button It is one of the following values e BUYNOW Buy Now button CART Add to Cart button GIFTCERTIFICATE Gift Certificate button SUBSCRIBE Subscribe button DO
19. 73 A HTML Variables for PayPal Payments Standard HTML Variables for the Instant Update API Required or Character Name Optional Description Length length unit Optional Unit of measure for the value specified by length x Allowable values are any values that you choose to provide PayPal passes the value to your callback server in callback requests 74 April 2012 Button Manager NVP API
20. BMButtonSearch Request Fields Field Description METHOD Required BMButtonSearch STARTDATE Required Starting date for the search The value must be in UTC GMT format for example 2009 08 24T05 38 48Z No wildcards are allowed ENDDATE Optional Ending date for the search The value must be in UTC GMT format for example 2010 05 01T05 38 48Z No wildcards are allowed BMButtonSearch Response The response contains a list of all hosted buttons and their associated characteristics BMButtonSearch Response Fields Field Description 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 TTEMNAMEN The item name It is a list of variables in which n is a digit between O and 9 inclusive 5 The date created or last changed It is a list of variables in which n is a digit between O and 9 inclusive L_MODIFYDATE 36 April 2012 Button Manager NVP API Button Manager API Reference BMGetButtonDetails API Operation BMButtonSearch Errors Error Code Short Message Long Message Correcting This Error 10001 Internal Error Internal Error 11994 Search Warning You have exceeded the maximum number of buttons that can be returned Please adjust your seach parameters if required 1199
21. Button Manager API With Hosted Solution Checkout For more information about Hosted Solution and the HTML variables that you can use see the Hosted Solution Guide 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 Log in to your PayPal account Select My Account Profile Click API Access from the Profile Summary Click Grant API Permission Click Configure a custom API authorization Enter your Partner API username as specified by your shopping cart or third party A ua A U N m Check each Button Manager API you want to provide access to C BMManageButtonStatus C BMCreateButton C BMUpdateButton C BMSetinventory C BMGetinventory C BMButtonSearch BMGetButtonDetails 8 Click Submit Button Manager NVP API April 2012 13 Si PayPal Payments Standard Button Manager API Overview Granting Third Party Permission for APIs 14 April 2012 Button Manager NVP API Using the Button Manager API With NVP 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 NVP e Offering Multiple Payment Option Subscriptions Using NVP e Offering Installment Plans Using NVP e Offering A
22. Button Manager NVP API Button Manager API Reference E BMSetinventory API Operation BMManageButtonStatus Request The request specifies the hosted button s ID and the status you want to set the button to 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 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 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 11993 Invalid Argument The button status value specified is not valid BMSetinventory API Operation Use the BMSet Inventory API operation to set the inventory level and inventory management features for the specified button When you set the inventory level for a button PayPal can track invento
23. E L_OPTION4BI ING INGFREQU INGFREQU INGFREQU INGFREQU ING ING L OPTIONITOTALBILLINGCYCII ECT2 value VARIABLE valu valu PERIO valu PERIO valu PERIO valu PERIO valu valu FREQU PERIO L_OPTION3TOTALBILLINGCYCLI ECT4 value EMI L_OPTION4AMOUNTO L_OPTION4BIL valu valu FREQU PERIO L_OPTION4TOTALBILLINGCYCLI Using the Button Manager API With NVP Offering Automatic Billing Using NVP e Third e 33 12 ENCYO valu e 32 34 ENCY1 valu e 31 34 ENCY2 valu e 3 34 ENCY3 valu e Fourth value EMI L_OPTION3AMOUNTO L_OPTION3BIL e 44 44 e Fifth Can 55 50 ESO value 2 e 1 DO value Month LLINGCYCLESO value 1 e 2 D1 value Month LLINGCYCLES1 value 1 e 3 D2 value Month LLINGCYCLES2 value 1 e 4 D3 value Month LLINGCYCLES3 value 1 ENCYO value 4 DO value Week ESO value 4 ENCYO value 5 DO value Month ESO value 3 Offering Automatic Billing Using NVP These examples show how to offer automatic billing One example shows how you can set various billing options the other example shows how you can set a minimum amount to be billed and allow the buyer to specify the actual amount April 2012 Button Manager NVP API Using the Button Manager API With NVP PER Tracking Inventory for Menu Items Using NVP Automatic b
24. L in a website and for a link in email BMCreateButton Response Fields Field Description WEBS T TR CODE HTML code for web pages EMAILLINK Code for email links links in other documents that support external links and links to the Hosted Solution checkout flow HOSTEDBUTTONID ID of a PayPal hosted button or a Hosted Solution token BMCreateButton 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 Argument The email or merchant ID specified is invalid Button Manager NVP API April 2012 27 28 Button Manager API Reference BMCreateButton API Operation Error Code Short Message Long Message Correcting This Error 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 11932 Invalid Data You must specify a corresponding number of entries for option names and selections 11933 Inv
25. NATE Donate button UNSUBSCRIBE Unsubscribe button VIEWCART View Cart button PAYMENTPLAN Installment Plan button since version 63 0 AUTOBILLING Automatic Billing button since version 63 0 The kind of button code It is one of the following values e HOSTED A secure button stored on PayPal e ENCRYPTED An encrypted button not stored on PayPal e CLEARTEXT An unencrypted button not stored on PayPal The use of button It is one of the following values e PRODUCTS button is used to purchase products e SERVICES button is used to purchase services ID of a PayPal hosted button HTML code for web pages Code for email links and links in other documents that support external links HTML standard button variables Option Details Fields Field Description OPTIONNNAME Optional The menu name It is one or more variables in which n is a digit between O and 4 inclusive for hosted buttons otherwise it is a digit between O and 9 inclusive April 2012 Button Manager NVP API Button Manager API Reference BMGetButtonDetails API Operation Option Selection Details Fields Field Description 1 OPTIONNSELECTX L_OPTIONOPRICEX OPTIONNTYP Gl Optional The menu item s name It is a list of variables for each OPTIONNNAI E in which x is a digit between 0 and 9 inclusive Optional The price
26. Optional Description Length le Optional Sets the language for the billing information log in page 2 only The default is US charset Optional Sets the character set and character encoding for the billing information log in page on the PayPal website In addition this variable sets the same values for information that you send to PayPal in your HTML button code The default is based on the language encoding settings in your Account Profile night phone a Optional The area code for U S phone numbers or the country code See for phone numbers outside the U S PayPal fills in the description buyer s home phone number automatically night phone b Optional The three digit prefix for U S phone numbers or the entire See phone number for phone numbers outside the U S description excluding country code PayPal fills in the buyer s home phone number automatically night phone c Optional The four digit phone number for U S phone numbers See PayPal fills in the buyer s home phone number description automatically state Optional State code 2 zip Optional Postal code 32 HTML Variables for the Instant Update API HTML variables for the Instant Update API set up the Cart Upload command for the Instant Update API callback Establish your own Instant Update callback server before you use these variables Instant Update Variables to Set Up a Payment for the Instant Update API Some Instant Update variables set up the Cart Upload to use your c
27. PayPal Button Manager API NVP Button Manager NVP API Document Number 10089 en US 201204 O 2012 PayPal Inc All rights reserved PayPal is a registered trademark of PayPal Inc The PayPal logo is a trademark of PayPal Inc Other trademarks and brands are the property of their respective owners The information in this document belongs to PayPal Inc It may not be used reproduced or disclosed without the written approval of PayPal Inc Copyright PayPal All rights reserved PayPal S r l et Cie S C A Soci t en Commandite par Actions Registered office 22 24 Boulevard Royal L 2449 Luxembourg R C S Luxembourg B 118 349 Consumer advisory The PayPal payment service is regarded as a stored value facility under Singapore law As such it does not require the approval of the Monetary Authority of Singapore You are advised to read the terms and conditions carefully 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 t
28. RL to which the buyer s browser is redirected when the inventory drops to O 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 Field Description ITEMNUMBER The ID for an item associated with this button ITEMOTY The current inventory level of the item associated with this button ITEMOTYDELTA ITEMALERT ITEMCOST Not used The quantity of the item associated with this button below which PayPal sends you an email notification The cost of the item associated with this button Option Tracking Details Fields Field Description L_OPTIONNUMBERN E L_OPTIONOTYN L_OPTIONSELECTN 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 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 O and 9 inclusive The menu item s name in a dropdown menu It is a list of variables for each menu item in which n is a digit between O and 9 inclusive April 2012 Button Manager NVP API Button Manager API Reference BMGetinventory API Operation Field De
29. TML Variables for Shopping Carts e e 59 HTML Variables for Recurring Payments Buttons 0 61 HTML Variables for Displaying PayPal Checkout Pages 67 HTML Variables for Filling Out PayPal Checkout Pages Automatically 70 HTML Variables for the Instant Update API 0 o 71 4 April 2012 Preface This document describes the Button Manager API for NVP Intended Audience This document is intended for merchants and developers implementing PayPal Payment Standard previously known as Website Payments Standard buttons using an API Revision History Revision history for Button Manager API NVP TABLE P 1 Revision History Date Description 04 03 12 Updated references to Website Payments Standard and Website Payments Pro to PayPal Payments Standard and PayPal Payments Pro respectively 02 13 12 Maintenance release 05 10 10 Added information about installment plans automatic billing and subscribe buttons 02 03 10 Added error code 01 11 10 Added download key information and updated for version 61 0 06 03 09 Added HTML Variable appendix and updated for version 57 0 03 31 09 Initial draft Button Manager NVP API April 2012 I Revision History 6 April 2012 Button Manager NVP API PayPal Payments Standard Button Manager API Overview The PayPal Payments Standard previously known as Website Payments Standard Bu
30. TONCODE TOKI E N BUTTONTYPE PAYMENT LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB LB EB LB LB LB LB LB LB LB LB LB LB LB LB U U ma ma TONVARO subtotal 11 TONVAR1 tax 2 ma ma ma TONVAR2 shipping 3 TONVAR3 handling 4 TONVAR4 Smith TONVARS5 1last_name Victor ma ma ma TONVAR6 address1l Gardens TONVAR7 address2 99343 TONVAR8 city Paris TONVAR9 state TX ma ma ma TONVAR10 zip 75002 TONVAR11 count ry US TONVAR12 billing first name V J TONVAR13 billing last name Smith ma ma ma TONVAR14 billing_address1 5088 061 Craven Hill Gardens TONVAR15 billing_address2 Apt 199343 ba TONVAR1 6 billing_city Wolverhampton TONVAR17 billing_state West Midlands ma ma ma TONVAR18 bi1ling_zip W12 410 TONVAR1 9 billing_country GB TONVAR20 night phone a 408 TONVAR21 night phone b 398 ma ma TONVAR22 night_phone_c 3065 TONVAR23 notify url www google com TONVAR24 custom customl TONVAR25 cancel_return http www cancel_return com ma ma PTONVAR2 6 paymentaction sale TTONVAR27 currency_ code GBP TONVAR28 business FLBY7TDW3HTYS PTONVAR29 invoice ma ma ma PTONVAR30 1c GB PTONVAR31 showBillingAddress false PTONVAR32 showShippingAddress false PTONVAR33 showBi111ingEmail true ma ma ma
31. al to 30 t3 Regular billing cycle units Must be specified for Subscribe buttons Button Manager NVP API April 2012 15 Using the Button Manager API With NVP Creating a Button Using NVP HTML Variable Notes 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 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 Party 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 Ie 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 PayPal Payments Standard
32. alid 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 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 April 2012 Button Manager NVP API Button Manager API Reference BMUpdateButton API Operation Gode Short Message Long Message Correcting This E
33. allback server Include the following required variables in the Cart Upload command to have PayPal send Instant Update requests to your callback server Include the following optional variables when appropriate Button Manager NVP API April 2012 71 A HTML Variables for PayPal Payments Standard HTML Variables for the Instant Update API HTML Variables to Set Up an Instant Update Payment Name callback url callback_timeou E callback_versio n fallback_tax_am ount fallback_shippi ng_option_name x fall back_shippi ng_option_amoun t_x fall back_shippi ng_option_is_de faul Tx Required or Optional Description Required The URL of your Instant Update callback server Required The timeout in seconds for callback responses from your Instant Update callback server After exceeding the timeout PayPal uses the fallback values on the Review Your Payment page for tax shipping and insurance Allowable values are 1 6 PayPal recommends the value 3 IMPORTANT Use values other than 3 only when instructed to do so by your PayPal representative Optional The version of the Instant Update API that your callback server uses The default is the current version Optional Tax amount to use as a fallback if the callback response times out Required Name and label of shipping option x to use as a fallback if the callback response times out For example Express 2 days Yo
34. amount0 lt option gt value 10 00 gt e Optional for Buy Now Add to Cart Subscribe Automatic Billing and Installment Plan buttons e Not used with Donate or Buy Gift Certificate buttons Button Manager NVP API April 2012 57 A HTML Variables for PayPal Payments Standard HTML Variables for Payment Transactions Required or Character Name Optional Description Length option select1 Optional For priced options the value of the second option selection 64 of the on0 dropdown menu For example lt option value medium gt small 10 00 lt option gt lt input type hidden name option select value medium gt You can specify a maximum of 10 option selections by incrementing the option selection index option select 0 through option select 9 NOTE A corresponding option selection in osO must also be set e Optional for Buy Now Add to Cart Subscribe Automatic Billing and Installment Plan buttons e Not used with Donate or Buy Gift Certificate buttons option_amount1 Optional For priced options the amount that you want to charge for 64 the 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_amount1 value 15 00 gt You can specify a maximum of 10 option amounts by incrementing the option amount index option amount O through option amount 9 NOTE A corresponding option selection in
35. an address and require one The default is 0 return Optional The URL to which PayPal redirects buyers browser after 1 024 they complete their payments For example specify a URL on your site that displays a Thank you for your payment page Default PayPal redirects the browser to a PayPal webpage rm Optional Return method The FORM METHOD used to send data to the 1 URL specified by the return variable Allowable values are e 0 all shopping cart payments use the GET method e 1 the buyer s browser is redirected to the return URL by using the GET method but no payment variables are included e 2 the buyer s browser is redirected to the return URL by using the POST method and all payment variables are included The default is 0 NOTE The rm variable takes effect only if the return variable is set Button Manager NVP API April 2012 69 70 HTML Variables for PayPal Payments Standard HTML Variables for Filling Out PayPal Checkout Pages Automatically Required or Character Name Optional Description Length cbt Optional Sets the text for the Return to Merchant button on the 60 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 NOTE The cbt variable takes effect only if the return variable is set cancel_
36. ance amount to use as a fallback if the callback nce amount response times out Include the fallback insurance option offered HTML variable if you specify an insurance amount The fallback insurance amount applies to all shipping options that you specify Instant Update Variables for Dimensions of Individual Items Shipping charges are calculated sometimes by using the dimensions of individual items in the shopping cart Include the following optional dimensional variables below in the Cart Upload command to provide the information to your callback server HTML Variables to Set Up an Instant Update Payment for Dimension Based Shipping Charges Required or Character Name Optional Description Length height x Optional Height of item x in the shopping cart Allowable values are positive integers height unit Optional Unit of measure for the values specified by the height x values Allowable values are any values that you choose to provide PayPal passes the value to your callback server in callback requests width x Optional Width of item x in the shopping cart Allowable values are positive integers width unit Optional Unit of measure for the value specified by width x Allowable values are any values that you choose to provide PayPal passes the value to your callback server in callback requests length x Optional Length of item x in the shopping cart Allowable values are positive integers Button Manager NVP API April 2012
37. associated with the first menu item It is a list of variables for each OPTIONONAME 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 Optional The installment option type for an OPTIONNNAME which is one of the following values e FULL Payment in full e VARIABLE Variable installments e EMI Equal installments NOTE Only available for Installment Plan buttons Installment Details F ield Description 1 OPTIONNBILLINGPERIODX L OPTIONNBILLINGPFREQUEN CYX L OPTIONNTOTALBILLINGCYC L ESX L_ OPTIONNAMOUNTX Optional The installment cycle unit which e NoBillingPeriodType None defaul Day Week SemiMonth Month Year is one of the following values U It is a list of variables for each OPTIONNNAI and 4 inclusive E in which x is a digit between O Optional The installment cycle frequency in units e g if the billing frequency is 2 and the billing period is Mont months The default billing frequency is 1 h the billing cycle is every 2 Itis a list of variables for each OPTIONNNAI E in which x is a digit between O and 4 inclusive Optional The total number of billing cycles regardless of the duration of a cycle 1 is the default It is a list of variables for each OPTIONNNAI E in which x is a digit between 0
38. bscribers do not see this field invoice Optional User defined field which must be unique with each 127 subscription The invoice number is shown to subscribers with the other details of their payments Button Manager NVP API April 2012 63 A HTML Variables for PayPal Payments Standard HTML Variables for Recurring Payments Buttons Required or Character Name Optional Description Length modify Optional Modification behavior 1 Allowable values are e 0 allows subscribers only to sign up for new subscriptions e 1 allows subscribers to sign up for new subscriptions and modify their current subscriptions e 2 allows subscribers to modify only their current subscriptions The default value is 0 usr manage Optional Set to 1 to have PayPal generate usernames and initial 1 passwords for subscribers Automatic Billing Button HTML Variables Required or Character Name Optional Description Length max_text Optional A description of the automatic billing plan The button set customer li Required mit min amount Optional creation tool uses the same value that you enter in the Description field Your button passes the description to PayPal to augment the item name in authorization notices and transaction details If you write the HTML code for your button manually the value of max text and the text above the button can differ Specify whether to let buyers enter maximum billing limits in a text box or choose from a
39. clusive 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 30 April 2012 Button Manager NVP API Button Manager API Reference E BMUpdateButton API Operation Field Description BUTTONIMAGEURL xs string Optional The button s URL NOTE Specify either the kind of button image or the URL BUYNOWTEXT 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 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 Optional The country in which the transaction occurs 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 Option Details Fields Field Description OPTIONNNAME Optional The menu name It is one or more variables in which n is a digit between O and 4 inclusive for hosted bu
40. cter length and limitations 1 single byte alphanumeric character 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 unavailable Character length and limitations 127 single byte alphanumeric characters Optional Whether to reuse download keys e 0 do not reuse keys default e 1 reuse keys NOTE If you do not reuse the download keys you must replenish the keys when you sell out of the product being downloaded 42 April 2012 Button Manager NVP API Button Manager API Reference E BMSetlnventory API Operation Field Description APPENDDIGITALDOWNLOADKEY Optional Whether to append download keys S e 0 do not append keys default e 1 append keys NOTE If you do not append the download keys unused keys will be replaced L DIGITALDOWNLOADKEYSn Optional One or more digital download keys up to a maximum of 1 000 keys The variable n in the field name is a number between O and 999 inclusive that specifies the key Character length and limitations 1 000 single byte alphanumeric characters each Item Tracking Details Fields ITEMNUMBER Optional The ID for an item associated with this button ITEMQTY The quantity you want to specify for the item associated with this button Specify either the
41. e 12 30 L OPTIONOBILLINGPERIODO value Month L_OPTIONOSELECT1 value Super L_OPTIONOPRICE1 value 1 30 L_OPTIONIBILLINGPERIODO value Month L OPTIONOSELECT2 value Premium L_OPTIONOPRICE2 value 1 30 L OPTION2BILLINGPERIODO value Month Offering Installment Plans Using NVP The example shows how to offer installment plans for both variable installments and equal monthly installments as well as payment in full Various billing cycles and frequencies are allowed L BUTTONVAR1 value item_name Example BUTTONTYPE value PAYMENTPLAN OPTIONONAME value Special Televesion L OPTIONOSELECTO value First L_OPTIONOPRICEO value 12 00 OPTIONOTYPE value FULL OPTIONITYPE value EMI L_OPTIONOSELECT1 value Second L_OPTIONIAMOUNTO value 12 23 L OPTIONIBILLINGFREQUENCYO value 2 L OPTIONIBILLINGPERIODO value Month Button Manager NVP API April 2012 17 18 L OPTIONOSE OPTION2TYPE L_OPTION2AMO L OPTION2BIL UNTO L OPTION2BI ING L_OPTION2TOTALBI L_OPTION2AMOUNT1 L OPTION2BI L OPTION2BI ING L_OPTION2TOTALBI L_OPTION2AMOUNT2 L OPTION2BI L OPTION2BIL ING L_OPTION2TOTALBI L_OPTION2AMOUNT3 L OPTION2BIL ING L OPTION2BI L_OPTION2TOTALBI L_OPTIONOSE ECT3 OPTION3TYPE L OPTION3BI ING L OPTIONOSE OPTION4TYP
42. e Add to Cart and View Cart buttons You can also use HTML variables supported the Cart Upload command Technical HTML Variables Technical HTML variables control how PayPal responds technically when people click PayPal Payments Standard payment 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 Allowable Values for the cmd HTML Variable Value of cmd Description _xclick The button that the person clicked was a Buy Now button _cart For shopping cart purchases The following 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 Cart buttons for the PayPal Shopping Cart e upload The Cart Upload command for third party carts _oe gift certificate The button that the person clicked was a Buy Gift Certificate button _xclick subscriptions The button that the person clicked was a Subscribe button _xclick auto billing The button that the person clicked was an Automatic Billing button _xclick payment plan The button that the person clicked was an Installment Plan button _donations The button that the person clicked was a Donate button _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 whic
43. e tax amount to bill for the cycle in addition to the base amount It is a list of variables for each OPTIONONAMI and 4 inclusive E in which x is a digit between 0 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 France Germany Hong Kong Italy Japan Mexico Netherlands Poland Spain e en English default de German default en English e en English default e nl Dutch r French e en English default e fr French en English default zh Chinese e fr French default en English e de German default e en English zh Chinese default en English e it Italian default e en English e ja Japanese default e en English es Spanish default en English e nl Dutch default e en English e pl Polish default e en English es Spanish default en English 26 April 2012 Button Manager NVP API Button Manager API Reference BMCreateButton API Operation Country Button Language Options Switzerland e de German default e fr French 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 HTM
44. etails Obtain information about the parameters associated with a button BMButtonSearch Obtain a list of all buttons BMGet Inventory Obtain the inventory levels associated with a button BMSet Inventory Specify the inventory levels associated with a button Hosted Solution Links Hosted Solution links are URLs you create with the Button Manager API to initiate the Hosted Solution checkout flow NOTE Although you can use the Button Manager API to create buttons that initiate the Hosted Solution checkout flow do not confuse a button for Hosted Solution with hosted buttons that you also create with the Button Manager API April 2012 Button Manager NVP API PayPal Payments Standard Button Manager API Overview Granting Third Party Permission for APIs You create the Hosted Solution checkout link dynamically when your buyer attempts to check out For example when your buyer clicks your check out button you call the BMCreateButton API operation to create the link and then redirect the buyer s browser to PayPal using the link The buyer then pays on the PayPal Hosted Solution page After making the payment PayPal returns the buyer to the page you specified when you created the link HTML variables control the presentation of the Hosted Solution pages the information contained on the pages and pages to which your customer can be returned to when leaving Hosted Solution pages For an example of setting up HTML variables see Using the
45. ght the sum of weight values is used to calculate the shipping charges for the payment Allowable values are decimals numbers with 2 significant digits to the right of the decimal point weight_unit Optional The unit of measure if weight is specified Allowable values are e lbs e kgs The default is lbs ond 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 Add to Cart Subscribe Automatic Billing and Installment Plan 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 7 option field names 6 with Subscribe buttons by incrementing the option name index on0 through on6 e Optional for Buy Now Add to Cart Subscribe Automatic Billing and Installment Plan buttons e Not used with Donate or Buy Gift Certificate buttons Button Manager NVP API April 2012 55 A HTML Variables for PayPal Payments Standard HTML Variables for Individual Items Required or Name Optional Description Character Length OSU Optional osl Optional 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 al
46. h default e fr French China worldwide e en English default e zh Chinese 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 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 e fr French e en English United States e en English default e fr French e es Spanish e 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 NVP API April 2012 33 El Button Manager API Reference BMUpdateButton API Operation BMUpdateButton Response Fields Field Description VEBSITECODE 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 BMUpdateButton Errors 34 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 s
47. h kind of button was clicked by decoding the encrypted code or by looking up the saved button in the merchant s account Button Manager NVP API April 2012 51 A HTML Variables for PayPal Payments Standard Technical HTML Variables 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 payment in the form of Instant Payment Notification messages hosted button i See Required for buttons that have been saved in PayPal See d description accounts otherwise not allowed description The identifier of a button that was saved in a merchant s PayPal account PayPal assigns the value when payment buttons are first created and saved in merchants PayPal accounts NOTE A merchant s PayPal account can have a maximum of 1 000 saved payment buttons bn Optional An identifier of the source that built the code for the button that the buyer clicked sometimes known as the build notation Specify a value using the following format lt Company gt _ lt Service gt _ lt Product gt _ lt Country gt Substitute lt Service gt with an appropriate value from the following list e BuyNow AddToCart Donate Subscribe AutomaticBilling InstallmentPlan BuyGiftCertifcate ShoppingCart Substitute lt Product gt with WPS always for Website Payments Standard payment buttons and for the Website Payments Standard Cart Upload command
48. ike the line he button is live for approximately two hours NOTE The PayPal Hosted Solution page displays a button identified as Pay Now to continue the checkout flow The Pay Now button on the PayPal page is is different than the Pay Now button created by the BMCreateButton API operation You may need to change the URL of the image source to avoid confusion 22 April 2012 Button Manager NVP API Button Manager API Reference The Button Manager API enables you to programatically create edit and delete PayPal Payments 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 only hosted buttons support button maintenance and inventory management e BMCreateButton API Operation MUpdateButton API Operation MButtonSearch API Operation MGetButtonDetails 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 PayPal Payments Standard button You can 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 to 5 menu
49. illing in which you specify the choices BUTTONTYPE value AUTOBILLING OPTIONONAME value Item 234 L_OPTIONOPRICEO value 12 30 L_OPTIONOPRICE1 value 14 30 L_OPTIONOPRICE2 value 15 30 L_OPTIONOPRICE3 value 16 30 Automatic billing in which you specify the minimum amount BUTTONTYPE value AUTOBILLING L_BUTTONVARO value item_name Item 123 L_BUTTONVARO value min_amount 12 34 Tracking Inventory for Menu Items Using NVP The example shows the NVP parameters that enable tracking of inventory and profit and loss The option number list index value specifies the position in the drop down menu for the option starting from 0 as in L_OPTIONNUMBERO TRACKINV 1 TRACKPNL 1 OPTIONINDEX 0 L_OPTIONNUMBERO 1001 L_OPTIONOQTY0 100 L_OPTIONALERT0 5 L OPTIONCOSTO 4 50 L_OPTIONNUMBER1 1002 L_OPTIONOTY1 200 L_OPTIONALERT1 5 L OPTIONCOST1 5 50 L_OPTIONNUMBER2 1003 L_OPTIONOTY2 150 L_OPTIONALERT2 5 L OPTIONCOST2 5 00 OLDOUTURL http YourSoldOutLandingPage html Button Manager NVP API April 2012 19 20 Using the Button Manager API With NVP Using the Button Manager API With Hosted Solution Checkout Using the Button Manager API With Hosted Solution Checkout The example shows the NVP parameters for creating a link to initiate the Hosted Solution checkout flow This example also creates a Pay Now button that can by used on your review page to initiate the Hosted Solution checkout flow BUT
50. included Pass through variable you can use to identify your invoice number for this purchase Default No variable is passed back to you 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 payment This value overrides the weight values of individual items Allowable values are decimals numbers with 2 significant digits to the right of the decimal point The unit of measure if weight_cart is specified Allowable values are e lbs e kgs The default value is lbs Character Length 1 256 127 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 Button Manager NVP API April 2012 59 A HTML Variables for PayPal Payments Standard HTML Variables for Shopping Carts HTML Variables for Shopping Carts Required or Character Name Optional Description Length add See Add an item 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 x Required The amount associa
51. ing cart or a 1 description custom shopping cart This variable must be set as follows upload 1 The alternatives are the add 1 variable and the display 1 variables which are used with the PayPal Shopping Cart HTML Variables for Recurring Payments Buttons Recurring Payments buttons are e Subscribe buttons e Automatic Billing buttons Button Manager NVP API April 2012 61 62 HTML Variables for PayPal Payments Standard HTML Variables for Recurring Payments Buttons e Installment Plan buttons HTML variables for recurring payments buttons set terms for different kinds of PayPal automatic payment plans Subscribe Button HTML Variables 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 If you are collecting 127 aggregate payments the value can be a summary of all items purchased a tracking number or a generic term such as subscription If this variable is omitted buyers see a field in which they can enter the item name currency code Optional The currency of prices for trial periods and the subscription 3 The 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 specify al Specify 2 description an integer value in the allowable range for
52. ipping methods they choose The cost of shipping each additional unit of this item If this variable is omitted and profile based shipping rates are configured buyers are charged an amount according to the shipping methods they choose This shipping variable is valid only for Buy Now and Add to Cart buttons 127 127 54 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard oa HTML Variables for Individual Items Required or Character Name Optional Description Length tax Optional Transaction based tax override variable Set this variable to a flat tax amount to apply to the payment 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 if any apply tax_rate Optional Transaction based tax override variable Set this variable toa 6 percentage that applies to the amount multiplied by 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 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 wei
53. items each of which can include up to 10 possible selections Button Manager NVP API April 2012 23 El Button Manager API Reference BMCreateButton API Operation BMCreateButton Request Fields Field Description METHOD Required BMCreateButton BUTTONCODE 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 Unsubscribe and Pay Now e ENCRYPTED An encrypted button not stored on PayPal default for View Cart button e CLEARTI Unsubscribe button e TOKEN Hosted Solution checkout flow default for Pay Now button Since version 65 1 E BUTTONTYP EXT An unencrypted button not stored on PayPal default for values e BUYNOW Buy Now button CARI A secure button not stored on PayPal used only to initiate the Required The kind of button you want to create It is one of the following T Add to Cart button GIFTCERTIFICATE Gift Certificate button SUBSCRIBE Subscribe button DONATE UNSU VI Donate button BSCRIBE Unsubscribe button EWCART View Cart button PAYMEN PLAN Installment Plan button since version 63 0 AUTOBILLING Automatic Billing button since version 63 0 PAYMEN Pay Now button since version 65 1 NOTE Do not specify BUYNOW if BUTTONCODE TOKEN specify PAYMENT instead Do
54. lections within an option A text box name specified is invalid Text box names must not exceed 64 characters The button code value specified is invalid An option name specified is invalid Option names must not exceed 64 characters An option selection value specified is invalid Option selection values must not exceed 64 characters An option price value specified is invalid Make sure any punctuation marks are in the correct places The button country value specified is invalid The button country and language code combination specified is invalid 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 The amount specified is invalid Make sure any punctuation marks are in the correct places The currency code value specified is invalid Subtotal amount is not valid Tax amount is not valid Handling amount is not valid Shipping amount is not valid BMButtonSearch API Operation Use the BMButtonSearch API operation to obtain a list of your hosted PayPal Payments Standard buttons Button Manager NVP API April 2012 35 4 Button Manager API Reference BMButtonSearch API Operation 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
55. list of maximum billing limits that you specify Allowable values are e max limit own your button displays a text box for buyers to enter their own maximums above a minimum billing limit that you set with the min_amount variable e max_limit_defined your button displays a dropdown menu of product options with prices to let buyers choose their maximum billing limits The minimum monthly billing limit if you have one Valid only if set_customer_limit max_limit_own 64 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard CS HTML Variables for Recurring Payments Buttons Installment Plan Buttons HTML Variables Required or Character Name Optional Description Length disp_tot Optional Display the total payment amount to buyers during checkout 1 Allowable values are e y display the total e N do not display the total The default is N option_index Required e If the button offers a single plan use 0 or use a number 1 not used for option fields without prices such as size and color e If the button offers plan options the cardinal number of the option field on0 through on9 with plan payment options Include option_index if the number for the single plan or options field is not 0 option selectn Required e Ifthe button offers a single plan the value attribute ofa 8 hidden input field named osn The value attributes of both elements must match as the following sample code show
56. lowable 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 select 0 and option amount 0 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 Add to Cart Subscribe Automatic Billing and Installment Plan 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 056 You can implement up to 5 option selections as dropdown menus and up to 2 option selections as test boxes NOTE A corresponding option field on0 through on6 must be defined e Optional for Buy Now Add to Cart Subscribe Automatic Billing and Installment Plan buttons e N
57. lt table gt 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 gt 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 os1 gt lt option value Small gt Small lt option value Large gt Larg lt select gt lt td gt lt tr gt lt table gt input type hidden name currency_code value USD gt lt i 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 10 00 vw Size 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 PayPal does not generate code for options Button Manager NVP API April 2012 9 PayPal Payments Standard Button Manager API Overview Button Hosting Button Hosting The Button Manager API can create four kinds of buttons hosted encrypted clear text and token buttons
58. nd View Cart e Donate e Buy Gift Certificate Button Manager NVP API April 2012 Si PayPal Payments Standard Button Manager API Overview Generated Button Code e Subscribe and Unsubscribe e Pay Now Hosted Sole Solution only e Installment Plan e Automatic Billing The following buttons are some of those that you can create using the Button Manager API Generated Button Code When you create a button PayPal responds by generating code that you can paste into your web page or document The generated code 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 merchants in every country can use all the buttons that can be created For example German merchants cannot use Subscribe buttons even though they can be 8 April 2012 Button Manager NVP API PayPal Payments Standard Button Manager API Overview REM Generated Button Code 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 This example shows the PayPal code for displaying a hosted Add to Cart button to sell a wireless mouse lt form target paypal action https www sandbox paypal com cgi bin webscr method post gt lt input type hidden name cmd value _s xclick gt lt input type hidden name hosted button id value 19218 gt
59. ng this process simpler When you specify the inventory for a button you can specify the usage of download keys e Whether the keys you specify should be appended to the current list of keys or whether the list of keys should be replaced which allows you to replenish the list of keys or replace the list entirely e Whether the list of keys are to be reused or not Button Manager NVP API April 2012 11 12 PayPal Payments Standard Button Manager API Overview Button Manager API Summary If you do not reuse keys PayPal will also notify you when the item is sold out meaning that there are no more keys available Specifying download keys with NVP The following example shows how you might create several keys using the BMSetButtonInventory API operation ETHOD BMSet Inventory HOSTEDBUTTONID 49760 REUSEDIGITALDOWNLOADKEYS 0 APPENDDIGITALDOWNLOADKEYS 1 L_DIGITALDOWNLOADKEYS0 3t snheostenthueirue97987ueitheunth L_DIGITALDOWNLOADKEYS1 L_DIGITALDOWNLOADKEYS2 3tsnh L_DIGITALDOWNLOADKEYS3 3t snh0923nth2349oeunh These keys are appended to existing keys for the item and should not be reused 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 BMGetButtonD
60. nitiate the Hosted Solution checkout flow They have a lifetime of approximately 2 hours if not used 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 Do not confuse a hosted button with a button used as part of Hosted Solution which is a product that supports token encrypted and cleartext buttons With hosted buttons you can Get a list of all hosted buttons which lets you identify buttons for further programmatic manipulation Get details about a hosted button which lets you to identify the parameters and values associated with a button April 2012 Button Manager NVP API PayPal Payments Standard Button Manager API Overview LM Inventory Management Using Hosted Buttons e Update a hosted button which lets you to change individual parameters such as price in a hosted button e Manage hosted button status currently you can only delete a button e Get and set inventory information associated with the button Inventory Management Using Hosted Buttons You can get or set the inventory level for the item associated with a hosted button You can also track inventory on options within an item such as color or size Ifyou enable inventory management for a button PayPal tracks inventory for you and also lets your buyer know if the item is sold out You can specify inventory tracking on an item by item basis and al
61. o make changes to any information herein without further notice Preface Chapter Chapter Contents 5 Intended Audience a 5 Revision HISLOM ses ds rs dd a id A A DS RS A A o DR 5 1 PayPal Payments Standard Button Manager API Overview 7 Button Manager Introduction o e e 7 Generated Button Code a 8 Button Hosting s ia s d darra waea a a a A 10 Hosted Button Manipulation a aoaaa e 10 Inventory Management Using Hosted Buttons a aoa oa a aa a 11 Inventory Management for Digital Downloads a aoa oa a a a 11 Button Manager API Summary aoaaa a 12 Hosted Solution Links a A 12 Granting Third Party Permission for APIS a aa aaa a a 13 2 Using the Button Manager API With NVP 15 Specifying HTML Variables oaoa a 15 Creating a Button Using NVP 0 a ee 16 Offering Multiple Payment Option Subscriptions Using NVP 17 Offering Installment Plans Using NVP o e a 17 Offering Automatic Billing Using NVP 0 0000002 a ee 18 Tracking Inventory for Menu Items Using NVP 0 e 19 Using the Button Manager API With Hosted Solution Checkout 20 Chapter 3 Button Manager API Reference 23 BMCreateButton API Operation A 23 BMCreateButton Request A 23 BMCreateButton Response e 27 BMCreateButton Errors
62. osO must also be set e Optional for Buy Now Add to Cart Subscribe Automatic Billing and Installment Plan buttons e Not used with Donate or Buy Gift Certificate buttons HTML Variables for Payment Transactions HTML variables for payment transactions provide information about entire payments regardless of the individual items involved with the payment You can use these variables with Add to Cart buttons and the Cart Upload command 58 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard A HTML Variables for Shopping Carts HTML Variables for Payment Transactions Name address override currency code custom handling invoice tax cart weight cart weight unit Required or Optional Optional Optional Optional Optional Optional Optional Optional Optional Description 1 The address specified with automatic fill in variables overrides the PayPal member s stored address Buyers see the addresses that you pass in but they cannot edit them PayPal does not show addresses if they are invalid or omitted The currency of the payment The default is USD Pass through variable for your own tracking purposes which buyers do not see Default No variable is passed back to you Handling charges This variable is not quantity specific The same handling cost applies regardless of the number of items on the order Default No handling charges are
63. oss 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 Button Manager NVP API April 2012 45 46 Button Manager API Reference BMSetlnventory API Operation Error Code Short Message Long Message Correcting This Error 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 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 Argument Item cost value must be specified when tracking profit amp loss by item 11984 Invalid A
64. ot used with Donate or Buy Gift Certificate buttons See description 64 or 200 See description 56 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard oa HTML Variables for Individual Items Required or Character Name Optional Description Length option_index See The cardinal number of the option field on0 through on9 description that has product options with different prices for each option Include option_index if the option field with prices is not ono e Optional for Buy Now Add to Cart Subscribe Automatic Billing and Installment Plan buttons e Not used with Donate or Buy Gift Certificate buttons Default 0 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 following 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 Add to Cart Subscribe Automatic Billing and Installment Plan buttons e Not used with Donate or Buy Gift Certificate buttons option_amount0 Optional For priced options the amount that you want to charge for 64 the first option selection of the on0 dropdown menu Use only numeric values the currency is taken from the currency_code variable For example lt option value small gt small 10 00 lt input type hidden name option_
65. pecified 44 April 2012 Button Manager NVP API Button Manager API Reference E BMSetlnventory API Operation Error Code Short Message Long Message Correcting This Error 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 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 invalid 11971 Invalid Data Inventory and or profit amp l
66. pecified 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 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 April 2012 Button Manager NVP API Button Manager API Reference E BMButtonSearch API Operation Error Code Short Message Long Message Correcting This Error 11936 11937 11938 11940 11941 11942 11943 11945 11947 11948 12210 13117 13118 13119 13120 Invalid Data Invalid Argument Invalid Argument Invalid Argument Invalid Argument Invalid Argument Invalid Argument Invalid Data Invalid Argument Invalid Argument Invalid Argument Invalid Argument Invalid Argument Invalid Argument Invalid Argument You cannot specify both an item price and prices for individual se
67. ponse contains a link to the URL to initiate the Hosted Solution payment flow identified in the response as EMATLLINK EMAILLINK https www paypal com hosted button id HSS The button variables control the presentation in the flow and the information that is provided to the customer initially Because the link is associated with a Hosted Solution token the link is live for approximately two hours after it is created If you initiate the Hosted Solution checkout from your review page you can alternatively use the HTML code in the response identified as HOSTEDBUTTONID to display a Pay Now button which you can programatically place in your review page WEBSITECODE lt form action https www paypal com cgi bin webscr method post gt lt input type hidden name cmd value _s xclick gt lt input type hidden name hosted button id value HSS gt lt input type image src https www paypal com en GB i btn btn paynow LG gif border 0 name submit alt PayPal The safer easier way to pay online gt lt img alt border 0 src https www stage2sc5398 qa paypal com en GB i scr pixel gif width 1 height 1 gt lt form gt Button Manager NVP API April 2012 21 E Using the Button Manager API With NVP Using the Button Manager API With Hosted Solution Checkout When your customer clicks the button he or she is redirected to the Hosted Solution payment flow L
68. r Installment Plan buttons Installment Details L OPTIONNBILLINGPERIODX Optional The installment cycle unit which is one of the following values e NoBillingPeriodType None default Day Week SemiMonth Month Year It is a list of variables for each OPTIONNNAME in which x is a digit between 0 and 4 inclusive L_OPTIONNBILLINGPFREQUEN Optional The installment cycle frequency in units e g if the billing CYx frequency is 2 and the billing period is Month the billing cycle is every 2 months The default billing frequency is 1 It is a list of variables for each OPTIONNNAME in which x is a digit between 0 and 4 inclusive L_OPTIONNTOTALBILLINGCYC Optional The total number of billing cycles regardless of the duration of a LESX cycle 1 is the default It is a list of variables for each OPTIONNNAME in which x is a digit between 0 and 4 inclusive L_OPTIONnNAMOUNTX Optional The base amount to bill for the cycle It is a list of variables for each OPTIONONAME in which x is a digit between 0 and 4 inclusive L OPTIONNSHIPPINGAMOUNTx Optional The shipping amount to bill for the cycle in addition to the base amount It is a list of variables for each OPTIONONAME in which x is a digit between 0 and 4 inclusive Button Manager NVP API April 2012 25 BMCreateButton API Operation Button Manager API Reference 1 OPTIONNTAXAMOUNTx Optional Th
69. r the absolute quantity in the quantity field It is a list of variables for each menu item in which n is a digit between O and 9 inclusive L_OPTIONALERTn Optional The quantity of the option associated with this menu item below which PayPal sends you an email notification It is a list of variables for each menu item in which n is a digit between O and 9 inclusive L_OPTIONCOSTn Optional The cost 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 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 BMSetinventory Response The response contains only the transaction ID BMSetInventory Response Fields Field Description TRANSACTIONID Transaction ID BMSetinventory Errors ari 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 TrackInv value must be specified 11955 Invalid Data A TrackPnl value must be s
70. return Optional A URL to which PayPal redirects the buyers browsers if 1 024 they cancel checkout before completing their payments For example specify a URL on your website that displays a Payment Canceled page Default PayPal redirects the browser to a PayPal webpage HTML Variables for Filling Out PayPal Checkout Pages Automatically HTML variables for filling out PayPal checkout pages automatically let you specify information about buyers PayPal recommends that you include automatic fill out variables with all of your payment buttons for consistent address handling in the checkout experience of your buyers NOTE When you pass in address_override 1 or tax or shipping variables PayPal HTML Variables for Filling Out PayPal Checkout Pages Automatically for Buyers displays the values in the payment widget Also PayPal hides the calculation widget regardless of setting up shipping and tax rates in your Account Profile Required or Character Name Optional Description Length address Optional Street 1 of 2 fields 100 address Optional Street 2 of 2 fields 100 city Optional City 40 country Optional Sets shipping and billing country 2 email Optional Email address 127 first name Optional First name 32 last name Optional Last name 64 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard a HTML Variables for the Instant Update API Required or Character Name
71. rgument 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 12210 Invalid Argument The currency code value specified is invalid April 2012 Button Manager NVP API Button Manager API Reference E BMGetinventory API Operation 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 BMGetinventory Request The hosted button ID identifies the button whose inventory you want to track BMGetIinventory Request Fields Field Description METHOD Required BMGet Inventory HOSTEDBUTTONID Required The ID of the hosted button whose inventory information you want
72. rror 12210 Invalid Argument The currency code value specified is invalid 13117 Invalid Argument Subtotal amount is not valid 13118 Invalid Argument Tax amount is not valid 13119 Invalid Argument Handling amount is not valid 13120 Invalid Argument Shipping amount is not valid BMUpdateButton API Operation Use the BMUpdateButton API operation to modify a PayPal Payments Standard button that is hosted on PayPal This operation replaces all fields in the specified button therefore you must specify a value for 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 BMUpdateButton Request Fields Field Description METHOD Required BMUpdateButton HOSTEDBUTTONID Required The ID of the hosted button you want to modify Button Manager NVP API April 2012 29 4 Button Manager API Reference BMUpdateButton API Operation Field Description BUTTONTYPE Required The kind of button you want to update It is one of the following values e BUYNOW Buy Now button e CART Add to Cart button e GIFTCERTIFICATE Gift Certificate button e SUBSCRIBE Subscribe button e DONATE Donate button e
73. ry calculate the gross profit associated with sales send you an alert when inventory drops below a specified quantity and manage sold out conditions Button Manager NVP API April 2012 41 El Button Manager API Reference BMSetinventory API Operation e BMSetInventory Request e BMSetInventory Response e BMSetInventory Errors BMSetinventory Request The request specifies inventory values related to a hosted button as well as inventory values that are specific to each menu item BMSeiInventory Request Fields Field Description METHOD Required BMSet Inventory 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 It is one of the following values e 0 do not track inventory e 1 track inventory TRACKPNL Required Whether to track the gross profit associated with inventory OPT IONNAME INDEX SOLDOUTURL REUSED IGITALDOWNLOADK EYS 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 BMSet Inventory Optional Option index which identifies the button Option index O is the menu that contains the price if one exists otherwise it is the first menu without a price Chara
74. s lt input type hidden name osn value pay in 4 gt lt input type hidden name option_selectn value pay in 4 gt e If the button offers plan options the value attribute of the radio button for plan option n The value attributes of both elements must match as the following sample code shows lt input type radio name osn value pay in 4 gt Pay in 4 installments lt input type hidden name option selectn value pay in 4 gt option_selectn_ Required e If the button offers plan options text next to the radio name button for plan option n e If the button offers a single plan text that describes the plan features For example you might use the text Pay in 4 installments Button Manager NVP API April 2012 65 A HTML Variables for PayPal Payments Standard HTML Variables for Recurring Payments Buttons Required or Character Name Optional Description Length option selectn Required Whether the single plan or plan option n offered by the 1 type button is paid in full in equal periods or in variable periods Allowable values are e F pay in full at checkout e E pay in equal periods beginning at checkout or sometime later e V pay in variable periods beginning at checkout option_selectn_ Required Amount of payment m am If the value of option_selectn_type is E the value of this variable applies to all payments in the plan option_selectn_ Required Duration of payment period m Specify the
75. scription L_OPTIONOTYDELTAN L_OPTIONALERTN 1 OPTIONCOSTN Not used It is a list of variables for each menu item in which n is a digit between O and 9 inclusive The quantity of the option associated with this menu item below which PayPal sends you an email notification It is a list of variables for each menu item in which n is a digit between O and 9 inclusive The cost 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 O and 9 inclusive BMGetInventory Errors Error Code Short Message Long Message Correcting This Error 10001 11950 11951 11953 11991 11992 Internal Error Invalid Data Invalid Argument Invalid Data Invalid Data Invalid Argument Internal Error A hosted button ID must be specified The hosted button ID specified is invalid You can only track inventory and profit amp loss for buy now cart or subscription buttons The hosted button id specified does not have any inventory or cost associated with it You do not have permissions to access this button Please check the hosted button ID and try again Button Manager NVP API April 2012 49 4 Button Manager API Reference BMGetinventory API Operation 50 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard You can use all variables supported for your button Buy Now Donation Subscrib
76. so by option such as color or size within the item An e mail alerts you if inventory 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 where your buyer s browser is redirected if the item is sold out You can also 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 Inventory Management for Digital Downloads If you use hosted buttons you can chose to specify a list of download keys which are keys that you define and are associated with the item being sold These keys are useful when you want to sell digital goods with a key to enable access To use this feature you set the inventory for the button to include one or more download keys up to a maximum of 1 000 keys These keys are then available when you get the inventory for a button For example when a customer orders software or music you could obtain an unused key from the list of download keys and email it to your customer so they can download the item You are responsible for choosing the appropriate key from the list and how it is used PayPal only stores the inventory of keys and does not track how a specific key is used although PayPal does provide options for maki
77. ted with item x To pass an aggregate amount for the entire cart use amount 1 Applies only to the Cart Upload command 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 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 x It must be less than the selling price of the associated item This amount is added to 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 Cart 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
78. to obtain L_DIGITALDOWNLOADKEYSn Optional One or more digital download keys up to a maximum of 1 000 keys The variable n in the field name is a number between O and 999 inclusive that specifies the key Character length and limitations 1 000 single byte alphanumeric characters each 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 It is one of the following values e 0 do not track inventory e 1 track inventory Button Manager NVP API April 2012 47 48 Button Manager API Reference BMGetlnventory API Operation Field Description TRACKPNL OPTIONNAME INDEX SOLDOUTURL 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 BMSet Inventory Option index which identifies the button Option index O 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 The U
79. tton Manager API lets you programatically create manage edit and delete PayPal 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 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 Inventory Management for Digital Downloads e Button Manager API Summary e Hosted Solution Links 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 PayPal 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 PayPal Payment Standard buttons programatically in the same way that you can manage them on PayPal from the My Saved Buttons page of your Profile NOTE You can access your My Saved Buttons page on PayPal by choosing My Saved Buttons from the Profile s My selling tools If no buttons exist the menu item is Create New Button You can use the API to create these Website Payment Standard and Hosted Sole Solution buttons e Buy Now e Add to Cart a
80. ttons otherwise it is a digit between O and 9 inclusive Option Selection Details Fields 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_OPTIONOPRICEX Optional The price associated with the first menu item It is a list of variables for each OPTIONONAME in which x is a digit between O and 9 inclusive NOTE If you specify a price you cannot set a button variable to amount OPTIONNTYPE Optional The installment option type for an OPTIONNNAME which is one of the following values e FULL Payment in full e VARIABLE Variable installments e EMI Equal installments NOTE Only available for Installment Plan buttons Button Manager NVP API April 2012 31 32 Button Manager API Reference BMUpdateButton API Operation Installment Details L_OPTIONNBILLINGPERIODX L_OPTIONNBILLINGPFREQUEN CYX L OPTIONNTOTALBILLINGCYC LESX 1 OPTIONNAMOUNTX L_OPTIONnNSHIPP INGAMOUNTX L_OPTIONNTAXAMOUNTX Optional The installment cycle unit which is one of the following values e NoBillingPeriodType None default Day Week SemiMonth Month Year It is a list of variables for each OPTIONNNAI and 4 inclusive E in which x is a digit between 0 Optional The installment cycle frequency in units e g if the billing frequency
81. u can include a maximum of 10 shipping options as fallbacks Substitute x with ordinal numbers starting with 0 Iinclude 1 instance of this variable with its index x set to 0 If you include just 1 instance include fallback shipping option is default x with its index x set to O and its value set to 1 Allowable values for x are 0 9 Required Shipping amount for option x to use as a fallback if the response times out Allowable values for x are 0 9 Required Indicates that shipping option x is the default and should be selected in the dropdown menu as a fallback if the response times out Only one shipping option can be the default for buyers Check that you set 1 instance only of fallback shipping option is default xto the value 1 Allowable values are e 1 shipping option x is the default shipping option e 0 shipping option x is not the default shipping option Allowable values for x are 0 9 Character Length 1024 1 50 72 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard a HTML Variables for the Instant Update API Required or Character Name Optional Description Length fallback_insura Optional Indicates that insurance is offered PayPal ignores this 1 nce_option_offe HTML variable if fallback_insurance_amount is red omitted or the value is 0 or less Allowable values are e 1 insurance is offered e O insurance is not offered fallback insura Optional Insur
82. 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 Description of item If this variable is omitted buyers enter their own name during checkout e Optional for Buy Now Donate Subscribe Automatic Billing Installment Plan and Add to Cart buttons e Not used with Buy Gift Certificate buttons Pass through variable for you to track product or service purchased or the contribution made The value you specify is passed back to you upon payment completion This variable is required if you want PayPal to track inventory or track profit and loss for the item the button sells 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 payment PayPal appends a sequence number to identify uniquely the item in the PayPal Shopping Cart for example quantity1 quantity2 and so on 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 shipping2 is not defined this flat amount is charged regardless of the quantity of items purchased This 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 sh
83. utomatic Billing Using NVP e Tracking Inventory for Menu Items Using NVP e Using the Button Manager API With Hosted Solution Checkout 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 PayPal Payments Standard button Although you can use the L_BUTTONVARn 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_OPTIONOPRICEn 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 O and less than or equ
84. xadecimal 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 Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command le Optional The language of the login or sign up page that subscribers 2 see when they click the Subscribe button If unspecified PayPal determines the language by using a cookie in the subscriber s browser If there is no PayPal cookie the default language is U S English 68 April 2012 Button Manager NVP API HTML Variables for PayPal Payments Standard A HTML Variables for Displaying PayPal Checkout Pages Required or Character Name Optional Description Length no note Optional Do not prompt buyers to include a note with their payments 1 Allowable values are e 0 provide a text box and prompt for the note e 1 hide the text box and the prompt The default is 0 cn Optional Label that appears above the note field This value is not 40 saved and does not appear in any of your notifications If this variable is 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 no_shipping Optional Do not prompt buyers for a shipping address 1 Allowable values are e 0 prompt for an address but do not require one e 1 do not prompt for an address e 2 prompt for

PayPal Website Payments Standard - 2012 - Button Manager API (NVP) User Guide

Contents

Download Pdf Manuals

Related Search

Related Contents