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 to make changes to any information herein without further notice.
This document describes the Button Manager API for SOAP.
Intended Audience
This document is intended for merchants and developers implementing Website Payment
Standard buttons using an API.
Revision History
Revision history for Website Payments Standard Button Manager API (SOAP).
TABLE P.1 Revision History
DateDescription
06/03/09Added HTML Variable appendix and updated for version 57.0.
03/31/09Initial draft.
Button Manager SOAP APIJune, 20095
Revision History
6June, 2009Button Manager SOAP API
1
Website Payments Standard
Button Manager API Overview
The Website Payments Standard Button Manager API allows you to programatically create,
manage, edit, and delete Website Payment Standard buttons, which are the same kind of
buttons that you can create from the PayPal Profile. Hosted buttons created by this API reside
on PayPal and can use all features, including inventory management; however, you can use
this API to create code for non-hosted Website Payment Standard buttons as well.
z Button Manager Introduction
z Generated Button Code
z Button Hosting
z Hosted Button Manipulation
z Inventory Management Using Hosted Buttons
z Button Manager API Summary
z 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 Website 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 Website 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 Selling Preferences column. If no buttons have been
created, the menu item is Create New Button.
You can use the API to create the following types of Website Payment Standard buttons:
z Buy Now
z Add to Cart and View Cart
z Donate
z Buy Gift Certificate
z Subscribe and Unsubscribe
The following buttons are some of those that you can create using the Button Manager API:
Button Manager SOAP APIJune, 20097
Website Payments Standard Button Manager API Overview
Generated Button Code
Generated Button Code
When you create a button, PayPal responds by providing code that you can paste into your
web page or document.
PayPal generates code that you can use for the button, which includes
z HTML code for including the button in web pages
z URL link code for adding buttons to email and documents that support links
NOTE: Not all buttons that can be created are available to merchants in every country; for
example, German merchants cannot use Subscribe buttons even though they can be
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.
The following example shows the PayPal code to display a hosted Add to Cart button for a
wireless mouse:
8June, 2009Button Manager SOAP API
Website Payments Standard Button Manager API Overview
For a link, PayPal does not generate code for options.
Button Hosting
Buttons that you can view on the My Saved Buttons page of your PayPal profile are called
hosted buttons because they reside on PayPal. The API can create three kinds of buttons:
hosted, encrypted, and clear text.
Button Manager SOAP APIJune, 20099
Website Payments Standard Button Manager API Overview
Hosted Button Manipulation
z Hosted buttons are stored on PayPal. The parameters associated with this kind of button are
secure.
Hosted buttons provide the greatest flexibility because you can instruct PayPal to change
them dynamically and PayPal maintains information about their state, such as the inventory
level associated with the button.
z Encrypted buttons are not stored on PayPal. The parameters associated with this kind of
button are encrypted.
Encrypted buttons are similar to hosted buttons with regards 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 only use an encrypted button if a hosted button
cannot be used.
z 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.
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.
Specifically, you can
z Get a list of all hosted buttons defined, which allows you to obtain a list of all your buttons
for further programatic manipulation
z Get details about a hosted button, which allows you to identify the parameters and values
associated with a button
z Update a hosted button, which allows you to change individual parameters, such as price,
in a hosted button
z Manage hosted button status; currently, you can only delete a button
z Get and set inventory information associated with the button
Inventory Management Using Hosted Buttons
If you use hosted buttons, you can set inventory values for the item associated with the button
and get inventory values for the item. You can also track inventory on options within an item,
such as color, size, and so on.
If you enable inventory management for a button, PayPal tracks inventory for you and also lets
your buyer know whether the item is sold out. You can specify inventory tracking on an itemby-item basis and also by option, such as color or size, within the item.
10June, 2009Button Manager SOAP API
Website Payments Standard Button Manager API Overview
You are alerted by e-mail if the inventory on hand falls below the threshold you specify. If an
item is sold out, you can specify whether or not to accept a payment anyway. Optionally, you
can specify a URL to which your buyer’s browser is redirected if the item is sold out.
Additionally, you can enable profit and loss tracking for an item or option associated with a
button. 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.
Button Manager API Summary
The Button Manager API is available for both NVP and SOAP.
API OperationDescription
BMCreateButtonCreate button code
BMUpdateButtonUpdate a hosted button
BMManageButtonStatusDelete a button
Button Manager API Summary
BMGetButtonDetailsObtain information about the parameters associated with a button
BMButtonSearchObtain a list of all buttons
BMGetInventoryObtain the inventory levels associated with a button
BMSetInventorySpecify the inventory levels associated with a button
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
1. Log in to your PayPal account.
2. Select My Account Profile.
3. Click “API Access” from the Profile Summary.
4. Click “Grant API Permission.”
5. Click to “Configure a custom API authorization.”
6. Enter your Partner API Username, as specified by your shopping cart or third party.
7. Click to check each Button Manager API to which you want to provide access:
Button Manager SOAP APIJune, 200911
Website Payments Standard Button Manager API Overview
Granting Third-Party Permission for APIs
8. Click Submit.
12June, 2009Button Manager SOAP API
Using the Button Manager API
2
These examples show basic Button Manager API capabilities. The examples show how to
create buttons and set inventory levels.
z Specifying HTML Variables
z Creating a Button Using SOAP
z Tracking Inventory for a Button Using SOAP
Specifying HTML Variables
When you create or update a button using the Button Manager API, you must specify the same
HTML variables that you specify when creating any Website Payments Standard button.
Although you can use the ButtonVar 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 VariableNotes
item_nameName or description of item. Must be specified for Add to Cart buttons.
Character length and limitations: 127 single-byte alphanumeric characters.
amountThe price or amount of the item. Required for Add to Cart buttons. May not
be used when a dropdown with price (L_OPTION0PRICE
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 (,).
a3Price 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 (,).
p3Regular billing cycle. Must be specified for Subscribe buttons. Limitations:
Must be a positive integer greater than 0 and less than or equal to 30
t3Regular billing cycle units. Must be specified for Subscribe buttons.
shopping_urlURL where recipients can shop and redeem gift certificates. Required for Gift
Certificate buttons. Character length and limitations: 255 single-byte
alphanumeric characters
n) is defined.
Button Manager SOAP APIJune, 200913
Using the Button Manager API
Creating a Button Using SOAP
HTML VariableNotes
no_noteMust 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.
businessSecure 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:
z A merchant or 3rd Party calling the API directly may specify an
unregistered email and create an unencrypted button only.
z 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_numberItem number or ID. Character length and limitations: 127 single-byte
alphanumeric characters.
lcIf specified, it overrides the value set in the ButtonCode field.
For a complete list of HTML variables and complete information, see HTML Variables for
Website Payments Standard.
Creating a Button Using SOAP
The example sets up a SOAP request message to create a button.
The Button Manager API enables you to programatically create, edit, and delete Website
Payment Standard buttons hosted on PayPal and track product inventory associated with these
buttons. You can also create non-hosted buttons with the Button Manager API; however,
button maintenance and inventory management are only supported for hosted buttons.
z BMCreateButton API Operation
z BMUpdateButton API Operation
z BMButtonSearch API Operation
z BMCreateButton API Operation
z BMManageButtonStatus API Operation
z BMSetInventory API Operation
z BMGetInventory API Operation
BMCreateButton API Operation
Use the BMCreateButton API operation to create a Website Payments Standard button. You
an create either a button that is hosted on PayPal or a non-hosted button.
z BMCreateButton Request
z BMCreateButton Response
z 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 five menu items, each of which can include up
to 10 possible selections.
Button Manager SOAP APIJune, 200919
Button Manager API Reference
BMCreateButton API Operation
BMCreateButton Request Fields
FieldDescription
ButtonCodeebl:ButtonCodeType
(Optional) The kind of button code to create. It is one of the following values:
z HOSTED - A secure button stored on PayPal; default for all buttons except
View Cart and Unsubscribe
z ENCRYPTED - An encrypted button, not stored on PayPal; default for View
Cart button
z CLEARTEXT - An unencrypted button, not stored on PayPal; default for
Unsubscribe button
ButtonTypeebl:ButtonTypeType
(Required) The kind of button you want to create. It is one of the following
values:
z BUYNOW - Buy Now button
z CART - Add to Cart button
z GIFTCERTIFICATE - Gift Certificate button
z SUBSCRIBE - Subscribe button
z DONATE - Donate button
z UNSUBSCRIBE - Unsubscribe button
z VIEWCART - View Cart button
ButtonSubTypeebl:ButtonSubTypeType
(Optional) The use of button you want to create. It is one of the following
values:
z PRODUCTS - button is used to purchase products; default for Buy Now and
Add to Cart buttons
z SERVICES - button is used to purchase services
20June, 2009Button Manager SOAP API
FieldDescription
ButtonVarxs:string
(Optional) HTML standard button variables, which are described in HTML
Variables for Website Payments Standard
It is a list of variables, in which
not include leading zeros.
Character length and limitations: 63 single-byte alphanumeric characters each
OptionDetailsns:OptionDetailsType
(Optional) Menu items
TextBoxxs:string
(Optional) Text description for a menu item
It is a list of variables, in which
ButtonImageebl:ButtonImageType
(Optional) The kind of button image. It is one of the following values:
z REG - regular; default unless a button URL is specified
z SML - small
z CC - small button image with credit card logos; not applicable for
Unsubscribe or View Cart buttons
Button Manager API Reference
BMCreateButton API Operation
n is a digit between 0 and 999, inclusive; do
n is a digit between 0 and 1, inclusive.
NOTE: Specify either the kind of button image or the URL.
ButtonImageURLxs:string
(Optional) The button’s URL
NOTE: Specify either the kind of button image or the URL.
BuyNowTextebl:BuyNowTextType
(Optional) The button text for a Buy Now button. It is one of the following
values:
z BUYNOW - button text is Buy Now; default
z PAYNOW - button text is Pay Now
SubscribeTextebl:SubscribeTextType
(Optional) The button text for a Subscribe button. It is one of the following
values:
z BUYNOW - button text is Buy Now
z SUBSCRIBE - button text is Subscribe; default
ButtonCountryebl:CountryCodeType
(Optional) The country in which the transaction occurs. See Country Codes
for a list of country codes. By default, it is the merchant’s country of
registration with PayPal.
ButtonLanguagexs: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
.
Button Manager SOAP APIJune, 200921
Loading...
+ 47 hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.