Button Manager API

The Button Manager API enables you to programmatically create, manage, edit, and delete PayPal Payments Standard buttons.

Alternatively, you can create payment buttons with all the same features using the Create a PayPal button page.

Introduction

Use the Button Manager API to create and manage buttons when you are creating more than just a few PayPal Payments Standard buttons or when you manage buttons for others. For example, you should use the Button Manager API if you provide a shopping cart for merchants.

The Button Manager API enables you to manage PayPal Payments Standard buttons programmatically in the same way that you can manage them from the My Saved Buttons page on paypal.com.

You can use this API to create the following PayPal Payments Standard and Website Payments Pro Hosted Solution buttons:

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 HTML code includes:

The following example shows the PayPal code for displaying a hosted Add to Cart button to sell a wireless mouse:

<form
  target="paypal"
  action="https://www.sandbox.paypal.com/cgi-bin/webscr"
  method="post"
>
  <input type="hidden" name="cmd" value="_s-xclick" />
  <input type="hidden" name="hosted_button_id" value="19218" />
  <table>
    <tbody>
      <tr>
        <td><input type="hidden" name="on0" value="Color" />Color</td>
      </tr>
      <tr>
        <td>
          <select name="os0">
            <option value="Red">Red $10.00</option>
            <option value="Blue">Blue $8.00</option>
            <option value="Green">Green $12.00</option>
          </select>
        </td>
      </tr>
      <tr>
        <td><input type="hidden" name="on1" value="Size" />Size</td>
      </tr>
      <tr>
        <td>
          <select name="os1">
            <option value="Small">Small</option>
            <option value="Large">Large</option>
          </select>
        </td>
      </tr>
    </tbody>
  </table>
  <input type="hidden" name="currency_code" value="USD" />
  <input
    type="image"
    src="https://www.paypalobjects.com/webstatic/en_US/i/btn/png/btn_addtocart_120x26.png"
    alt="Add to Cart"
    name="submit"
  />
  <img
    alt=""
    src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif"
    width="1"
    height="1"
  />
</form>

This sample code creates an Add to Cart button with drop-down menus for Color and Size options.

The PayPal-generated code for a link would be as follows:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=19218

For a link, PayPal does not generate code for options.

Button hosting

The Button Manager API can create the following types of buttons:

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 Website Payments Pro Hosted Solution, which is a product that supports token, encrypted, and clear text buttons.

With hosted buttons, you can:

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.

If you 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 also 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 choose 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 making this process simpler.

When you specify the inventory for a button, you can specify the usage of download keys:

If you do not reuse keys, PayPal also notifies you when the item is sold out, which means that no more keys are available.

Specifying download keys with NVP

The following example shows how you might create several keys using the BMSetButtonInventory API operation:

METHOD=BMSetInventory
...
HOSTEDBUTTONID=49760
REUSEDIGITALDOWNLOADKEYS=0
APPENDDIGITALDOWNLOADKEYS=1
L_DIGITALDOWNLOADKEYS0=3tsnheostenthueirue97987ueitheunth
L_DIGITALDOWNLOADKEYS1=
L_DIGITALDOWNLOADKEYS2=3tsnh
L_DIGITALDOWNLOADKEYS3=3tsnheostenthueirue97987ueitheunth

These keys are appended to existing keys for the item and should not be reused.

Button Manager API summary

You can integrate with the Button Manager API by using either name-value pairs (NVP) or SOAP. For detailed information on the following Button Manager API operations and their fields, see the NVP/SOAP API reference.

Website Payments Pro Hosted Solution links

Website Payments Pro Hosted Solution links are URLs you create with the Button Manager API to initiate the Website Payments Pro Hosted Solution checkout flow.

You create the Website Payments Pro 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 Website Payments Pro 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 Website Payments Pro Hosted Solution pages, the information contained on the pages, and pages to which your customer can be returned to when leaving Website Payments Pro Hosted Solution pages. For an example of setting up HTML variables, see Checkout flow with Website Payments Pro Hosted Solution.

For more information about Website Payments Pro Hosted Solution and the HTML variables that you can use, see the Website Payments Pro Hosted Solution Guide.

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

Complete these steps to grant third-party permissions:

Examples >>