Button Manager API Examples

The following topics show basic capabilities of the Button Manager API and include examples.

Specify 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 NVP field (or ButtonVar in SOAP) 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_OPTION0PRICEn) is defined. Limitations: Value must be a positive number. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
a3 Price of subscription. Must be specified for Subscribe buttons. Value must be a positive number. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
p3 Regular billing cycle. Must be specified for Subscribe buttons. Limitations: Must be a positive integer greater than 0 and less than or equal to 30
t3 Regular billing cycle units. Must be specified for Subscribe buttons.
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:
  • A merchant or 3rd Party calling the API directly may specify an unregistered email and create an unencrypted button only.
  • 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.
lc If specified, it overrides the value set in the BUTTONCODE field.

For a complete description of all HTML variables, see HTML Variables for PayPal Payments Standard.

Create 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=CART
L_BUTTONVAR0=business=merchant@abc.com
L_BUTTONVAR1=item_name=Wireless%20Mouse
L_BUTTONVAR2=amount=10.50
L_BUTTONVAR3=no_shipping=1
L_BUTTONVAR4=currency_code=USD
L_BUTTONVAR5=no_note=1
OPTION0NAME=Color
L_OPTION0SELECT0=Red
L_OPTION0SELECT1=Blue
L_OPTION0SELECT2=Green
L_OPTION0PRICE0=10.00
L_OPTION0PRICE1=8.00
L_OPTION0PRICE2=12.00
OPTION1NAME=Size
L_OPTION1SELECT0=Small
L_OPTION1SELECT1=Large
BUTTONIMAGE=reg
...

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_BUTTONVAR0, and such), enable you to specify the same HTML variables as you ordinarily do using PayPal Payments Standard.

Create a button using SOAP

The example sets up a SOAP request message to create a button.

<com.paypal.soap.api.BMCreateButtonRequestType>
  <buttonType>
    <__value__>
      <m__value>CART</m__value>
    </__value__>
  </buttonType>
  <buttonCode>
    <__value__>
      <m__value>HOSTED</m__value>
    </__value__>
  </buttonCode>
  <buttonSubType>
    <__value__>
      <m__value>PRODUCTS</m__value>
    </__value__>
  </buttonSubType>
  <buttonVar>
    <string>business=XX-usbiz@paypal.com</string>
    <string>item_name=Item-123</string>
    <string>item_number=#1234</string>
    <string>shipping=0.50</string>
    <string>tax_rate=2.50</string>
    <string>address1=</string>
    <string>state=</string>
    <string>city=</string>
    <string>zip=</string>
    <string>no_shipping=0</string>
    <string>address_override=0</string>
  </buttonVar>

  <optionDetails>
    <com.paypal.soap.api.OptionDetailsType>
      <optionName>DD1</optionName>
      <optionSelectionDetails>
        <com.paypal.soap.api.OptionSelectionDetailsType>
          <optionSelection>AAAA</optionSelection>
          <price>1.55</price>
        </com.paypal.soap.api.OptionSelectionDetailsType>
        <com.paypal.soap.api.OptionSelectionDetailsType>
          <optionSelection>BBBB</optionSelection>
          <price>10.55</price>
        </com.paypal.soap.api.OptionSelectionDetailsType>
        <com.paypal.soap.api.OptionSelectionDetailsType>
          <optionSelection>CCCCC</optionSelection>
          <price>10.55</price>
        </com.paypal.soap.api.OptionSelectionDetailsType>
      </optionSelectionDetails>
    </com.paypal.soap.api.OptionDetailsType>

    <com.paypal.soap.api.OptionDetailsType>
      <optionName>DD2</optionName>
      <optionSelectionDetails>
        <com.paypal.soap.api.OptionSelectionDetailsType>
          <optionSelection>XXXX</optionSelection>
        </com.paypal.soap.api.OptionSelectionDetailsType>
        <com.paypal.soap.api.OptionSelectionDetailsType>
          <optionSelection>ZZZZ</optionSelection>
        </com.paypal.soap.api.OptionSelectionDetailsType>
      </optionSelectionDetails>
    </com.paypal.soap.api.OptionDetailsType>
  </optionDetails>

  <buttonImage>
    <__value__>
      <m__value>REG</m__value>
    </__value__>
  </buttonImage>
  <buttonImageURL></buttonImageURL>
  <buyNowText>
    <__value__>
      <m__value>BUYNOW</m__value>
    </__value__>
  </buyNowText>
  <subscribeText>
    <__value__>
      <m__value>SUBSCRIBE</m__value>
    </__value__>
  </subscribeText>
  <buttonCountry>
    <__value__>
      <m__value>US</m__value>
    </__value__>
  </buttonCountry>
  <buttonLanguage></buttonLanguage>
</com.paypal.soap.api.BMCreateButtonRequestType>

Offer multiple payment option subscriptions using NVP

The example shows how to create a Subscribe button for 3 kinds of payment options.

...
BUTTONTYPE value=SUBSCRIBE
OPTION0NAME value="Special TV"
L_OPTION0SELECT0 value="Regular"
L_OPTION0PRICE0 value="12.30"
L_OPTION0BILLINGPERIOD0 value="Month"
L_OPTION0SELECT1 value="Super"
L_OPTION0PRICE1 value="1.30"
L_OPTION1BILLINGPERIOD0 value="Month"
L_OPTION0SELECT2 value="Premium"
L_OPTION0PRICE2 value="1.30"
L_OPTION2BILLINGPERIOD0 value="Month"
...

Offer 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
OPTION0NAME value="Special Televesion"
L_OPTION0SELECT0 value="First"
L_OPTION0PRICE0 value="12.00"
OPTION0TYPE value="FULL"
OPTION1TYPE value="EMI"
L_OPTION0SELECT1 value="Second"
L_OPTION1AMOUNT0 value=12.23
L_OPTION1BILLINGFREQUENCY0 value=2
L_OPTION1BILLINGPERIOD0 value=Month
L_OPTION1TOTALBILLINGCYCLES0 value=2
L_OPTION0SELECT2 value="Third"
OPTION2TYPE value="VARIABLE"
L_OPTION2AMOUNT0 value="33.12"
L_OPTION2BILLINGFREQUENCY0 value=1
L_OPTION2BILLINGPERIOD0 value=Month
L_OPTION2TOTALBILLINGCYCLES0 value=1
L_OPTION2AMOUNT1 value="32.34"
L_OPTION2BILLINGFREQUENCY1 value=2
L_OPTION2BILLINGPERIOD1 value=Month
L_OPTION2TOTALBILLINGCYCLES1 value=1
L_OPTION2AMOUNT2 value="31.34"
L_OPTION2BILLINGFREQUENCY2 value=3
L_OPTION2BILLINGPERIOD2 value=Month
L_OPTION2TOTALBILLINGCYCLES2 value=1
L_OPTION2AMOUNT3 value="3.34"
L_OPTION2BILLINGFREQUENCY3 value=4
L_OPTION2BILLINGPERIOD3 value=Month
L_OPTION2TOTALBILLINGCYCLES3 value=1
L_OPTION0SELECT3 value="Fourth"
OPTION3TYPE value="EMI"
L_OPTION3AMOUNT0 value="44.44"
L_OPTION3BILLINGFREQUENCY0 value=4
L_OPTION3BILLINGPERIOD0 value=Week
L_OPTION3TOTALBILLINGCYCLES0 value=4
L_OPTION0SELECT4 value="Fifth"
OPTION4TYPE value="EMI"
L_OPTION4AMOUNT0 value="55.55"
L_OPTION4BILLINGFREQUENCY0 value=5
L_OPTION4BILLINGPERIOD0 value=Month
L_OPTION4TOTALBILLINGCYCLES0 value=3
...

Offer 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.

Automatic billing in which you specify the choices

...
BUTTONTYPE value= AUTOBILLING
OPTION0NAME value= "Item-234"
L_OPTION0PRICE0 value= "12.30"
L_OPTION0PRICE1 value= "14.30"
L_OPTION0PRICE2 value= "15.30"
L_OPTION0PRICE3 value= "16.30"
...

Automatic billing in which you specify the minimum amount

...
BUTTONTYPE value=AUTOBILLING
L_BUTTONVAR0 value="item_name=Item-123"
L_BUTTONVAR0 value="min_amount=12.34"
...

Track 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_OPTIONNUMBER0.

...
TRACKINV=1
TRACKPNL=1
OPTIONINDEX=0
L_OPTIONNUMBER0=1001
L_OPTIONQTY0=100
L_OPTIONALERT0=5
L_OPTIONCOST0=4.50
L_OPTIONNUMBER1=1002
L_OPTIONQTY1=200
L_OPTIONALERT1=5
L_OPTIONCOST1=5.50
L_OPTIONNUMBER2=1003
L_OPTIONQTY2=150
L_OPTIONALERT2=5
L_OPTIONCOST2=5.00
SOLDOUTURL=https://example.com/soldout

Track inventory for a button using SOAP

The example shows the SOAP parameters that enable tracking of inventory and profit and loss for a button.

<com.paypal.soap.api.BMSetInventoryRequestType>
  <hostedButtonID>41</hostedButtonID>
  <trackInv>1</trackInv>
  <trackPnl>1</trackPnl>
  <itemTrackingDetails>
    <itemNumber>234234</itemNumber>
    <itemQty>10</itemQty>
    <itemAlert>2</itemAlert>
    <itemCost>4</itemCost>
  </itemTrackingDetails>
  <soldoutURL>https://www.example.com/soldout</soldoutURL>
</com.paypal.soap.api.BMSetInventoryRequestType>

Checkout flow with Website Payments Pro Hosted Solution

The example shows the NVP parameters for creating a link to initiate the Website Payments Pro Hosted Solution checkout flow. This example also creates a Pay Now button that can by used on your review page to initiate the Website Payments Pro Hosted Solution checkout flow.

...
BUTTONCODE=TOKEN
BUTTONTYPE=PAYMENT
L_BUTTONVAR0=subtotal=11
L_BUTTONVAR1=tax=2
L_BUTTONVAR2=shipping=3
L_BUTTONVAR3=handling=4
L_BUTTONVAR4=Smith
L_BUTTONVAR5=last_name=Victor
L_BUTTONVAR6=address1=Gardens
L_BUTTONVAR7=address2=99343
L_BUTTONVAR8=city=Paris
L_BUTTONVAR9=state=TX
L_BUTTONVAR10=zip=75002
L_BUTTONVAR11=country=US
L_BUTTONVAR12=billing_first_name=V. J.
L_BUTTONVAR13=billing_last_name=Smith
L_BUTTONVAR14=billing_address1=5088 - 061 Craven Hill Gardens
L_BUTTONVAR15=billing_address2=Apt# 199343 ba
L_BUTTONVAR16=billing_city=Wolverhampton
L_BUTTONVAR17=billing_state=West Midlands
L_BUTTONVAR18=billing_zip=W12 4LQ"
L_BUTTONVAR19=billing_country=GB
L_BUTTONVAR20=night_phone_a=408
L_BUTTONVAR21=night_phone_b=398
L_BUTTONVAR22=night_phone_c=3065
L_BUTTONVAR23=notify_url=www.google.com
L_BUTTONVAR24=custom=custom1
L_BUTTONVAR25=cancel_return=https://example.com
L_BUTTONVAR26=paymentaction=sale
L_BUTTONVAR27=currency_code=GBP
L_BUTTONVAR28=business=FLBY7TDW3HTYS
L_BUTTONVAR29=invoice=
L_BUTTONVAR30=lc=GB
L_BUTTONVAR31=showBillingAddress=false
L_BUTTONVAR32=showShippingAddress=false
L_BUTTONVAR33=showBillingEmail=true
L_BUTTONVAR33=showBillingPhone=true
L_BUTTONVAR34=showCustomerName=true
L_BUTTONVAR35=showCardInfo=true
L_BUTTONVAR36=showHostedThankyouPage=true
L_BUTTONVAR37=bn=GBD
L_BUTTONVAR39=address_override=0
L_BUTTONVAR41=logoText=MartWall
L_BUTTONVAR42=logoImage=https://example.com/logo.gif
L_BUTTONVAR43=logoImagePosition=center
L_BUTTONVAR44=logoFont=Arial Bold
L_BUTTONVAR45=logoFontSize=24px
L_BUTTONVAR46=logoFontColor=#f0ff0f
L_BUTTONVAR47=bodyBgImg=sdf
L_BUTTONVAR48=bodyBgColor=#AEAEAE
L_BUTTONVAR49=headerHeight=70px
L_BUTTONVAR50=headerBgColor=#4B6BA1
L_BUTTONVAR51=PageTitleTextColor=Blue
L_BUTTONVAR52=PageCollapseBgColor=Blue
L_BUTTONVAR53=PageCollapseTextColor=Yellow
L_BUTTONVAR54=PageButtonBgColor=Blue
L_BUTTONVAR55=PageButtonFgColor=White
L_BUTTONVAR56=orderSummaryBgColor=#EDF2F7
L_BUTTONVAR57=orderSummaryBgImage=https://example.com/ordersummary.jpg
L_BUTTONVAR58=footerTextColor=#333333
L_BUTTONVAR59=footerTextlinkColor=#00f00f
L_BUTTONVAR60=template=templateC
L_BUTTONVAR61=return=https://example.com">

The response contains a link to the URL to initiate the Website Payments Pro Hosted Solution payment flow, identified in the response as EMAILLINK:

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 Website Payments Pro Hosted Solution token, the link is live for approximately two hours after it is created.

If you initiate the Website Payments Pro 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=<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="hosted_button_id" value="HSS-...">
<input type="image" src="https://www.paypalobjects.com/webstatic/en_US/i/btn/png/btn_paynow_107x26.png" alt="Pay Now"">
<img alt="" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
</form>

When your customer clicks the button, he or she is redirected to the Website Payments Pro Hosted Solution payment flow. Like the line, he button is live for approximately two hours.

Note: The PayPal Website Payments Pro 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.

HTML Variables >>