PayPal Payments Standard Button Manager API Overview
The PayPal Payments Standard (previously known as Website Payments Standard) Button 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.
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.
You can use the API to create these Website Payment Standard and Hosted Sole Solution buttons:
- Buy Now
- Add to Cart and View Cart
- Buy Gift Certificate
- Subscribe and Unsubscribe
- Pay Now (Hosted Sole Solution only)
- Installment Plan
- Automatic Billing
The following buttons are some of those that you can create using the Button Manager API:
Note For a complete list of PayPal button images and logos, see the Button Image Reference.
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:
- HTML code for including the button in web pages
- URL link code for adding buttons to email and documents that support links
This 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> <tr><td><input type="hidden" name="on0" value="Color">Color</td></tr><tr><td><select name="os0"> <option value="Red">Red $10.00 <option value="Blue">Blue $8.00 <option value="Green">Green $12.00 </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 value="Large">Large </select> </td></tr> </table> <input type="hidden" name="currency_code" value="USD"> <input type="image" src="https://www.sandbox.paypal.com/en_US/i/btn/btn_cart_LG.gif" border="0" name="submit" alt=""> <img alt="" border="0" src="https://www.sandbox.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1"> </form>
When you display a web page with this code, this button appears:
PayPal-generated code for a link would be as follows:
For a link, PayPal does not generate code for options.
The Button Manager API can create four kinds of buttons: hosted, encrypted, clear text, and token buttons. 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 initiate 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
- Update a hosted button, which lets you to change individual parameters, such as price, in a hosted button
- Manage hosted button status; currently, you can only delete a button
- 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.
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 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 making this process simpler.
When you specify the inventory for a button, you can specify the usage of download keys:
- 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
- Whether the list of keys are to be reused or not
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
following example shows how you might create several keys using
BMSetButtonInventory API operation:
METHOD=BMSetInventory ... HOSTEDBUTTONID=49760 REUSEDIGITALDOWNLOADKEYS=0 APPENDDIGITALDOWNLOADKEYS=1 L_DIGITALDOWNLOADKEYS0=3tsnheostenthueirue97987ueitheunth L_DIGITALDOWNLOADKEYS1= L_DIGITALDOWNLOADKEYS2=3tsnh L_DIGITALDOWNLOADKEYS3=3tsnh0923nth2349oeunh
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.
||Create button code|
||Update a hosted button|
||Delete a button|
||Obtain information about the parameters associated with a button|
||Obtain a list of all buttons|
||Obtain the inventory levels associated with a button|
||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.
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
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 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.
- Check each Button Manager API you want to provide access
- Click Submit.