PayPal Website Payments Standard - 2012 User Manual

Button Manager API (SOAP)

Last updated: April 2012

Button Manager SOAP API Document Number: 10090.en_US-201204

© 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, L2449, 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 i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information co ntained 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 f rom 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.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 1 PayPal Payments Standard Button Manager API Overview . 7

Button Manager Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Generated Button Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Button Hosting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Hosted Button Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Inventory Management Using Hosted Buttons. . . . . . . . . . . . . . . . . . . . . . . . 11

Inventory Management for Digital Downloads . . . . . . . . . . . . . . . . . . . . . . . . 11

Button Manager API Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Hosted Solution Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Granting Third-Party Permission for APIs . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 2 Using the Button Manager API With SOAP . . . . . . . . . 15

Specifying HTML Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Creating a Button Using SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Tracking Inventory for a Button Using SOAP . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 3 Button Manager API Reference . . . . . . . . . . . . . . . 19

BMCreateButton API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

BMCreateButton Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

BMCreateButton Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

BMCreateButton Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

BMUpdateButton API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

BMUpdateButton Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

BMUpdateButton Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

BMUpdateButton Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

BMButtonSearch API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

BMButtonSearch Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

April 2012 3

Contents

BMButtonSearch Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

BMButtonSearch Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

BMGetButtonDetails API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

BMGetButtonDetails Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

BMGetButtonDetails Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

BMGetButtonDetails Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

BMManageButtonStatus API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

BMManageButtonStatus Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

BMManageButtonStatus Response . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

BMManageButtonStatus Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

BMSetInventory API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

BMSetInventory Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

BMSetInventory Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

BMSetInventory Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

BMGetInventory API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

BMGetInventory Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

BMGetInventory Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

BMGetInventory Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Appendix A HTML Variables for PayPal Payments Standard . . . . . .55

Technical HTML Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

HTML Variables for Individual Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

HTML Variables for Payment Transactions . . . . . . . . . . . . . . . . . . . . . . . . . 62

HTML Variables for Shopping Carts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

HTML Variables for Recurring Payments Buttons . . . . . . . . . . . . . . . . . . . . . . 65

HTML Variables for Displaying PayPal Checkout Pages . . . . . . . . . . . . . . . . . . 71

HTML Variables for Filling Out PayPal Checkout Pages Automatically . . . . . . . . . . . 74

HTML Variables for the Instant Update API . . . . . . . . . . . . . . . . . . . . . . . . . 75

4 April 2012

Preface

This document describes the Button Manager API for SOAP.

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 (SOAP).

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 billin g, 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 appendi x and updated for version 57.0. 03/31/09 Initial draft.

Button Manager SOAP API April 2012 5

Revision History

6 April 2012 Button Manager SOAP API

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 S tandard buttons as well.

 Button Manager Introduction  Generated Button Code  Button Hosting  Hosted Button Manipulation  Inventory Management Using Hosted Buttons  Inventory Management for Digital Downloads  Button Manager API Summary  Hosted Solution Links  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:

 Buy Now  Add to Cart and View Cart  Donate  Buy Gift Certificate

Button Manager SOAP API April 2012 7

PayPal Payments Standard Button Manager API Overview

Generated Button Code

 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:

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

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 SOAP API

PayPal Payments Standard Button Manager API Overview

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:

<form target="paypal" action=" https://www.sandbo x.paypal.com/cgibin/webscr" method="post"> <input type="hidden" name="cmd " value="_s-xclick "> <input type="hidden" name="hos ted_button_id" val ue="19218"> <table> <tr><td><input type="hidden" n ame="on0" value="Color">Color</td></tr>< tr><td><select nam e="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" n ame="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="cur rency_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.paypa l.com/en_US/i/scr/pix el.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:

https://www.sandbox.paypal.com /cgi-bin/webscr?cm d=_sxclick&hosted_button_id=19218

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

Button Manager SOAP API April 2012 9

PayPal Payments Standard Button Manager API Overview

Button Hosting

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

10 April 2012 Button Manager SOAP API

PayPal Payments Standard Button Manager API Overview

Inventory Management Using Hosted Buttons

 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 key s, 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.

T o 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 replen ish 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.

Button Manager SOAP API April 2012 11

PayPal Payments Standard Button Manager API Overview

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 BMGetButtonDetails Obtain information about the parameters associated with a button BMButtonSearch Obtain a list of all buttons BMGetInventory Obtain the inventory levels associated with a button BMSetInventory 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.

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.

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.

12 April 2012 Button Manager SOAP API

PayPal Payments Standard Button Manager API Overview

Granting Third-Party Permission for APIs

5. Click Configure a custom API authorization.

6. Enter your Partner API username, as specified by your shopping cart or third party.

7. Check each Button Manager API you want to provide access to:

8. Click Submit.

Button Manager SOAP API April 2012 13

PayPal Payments Standard Button Manager API Overview

Granting Third-Party Permission for APIs

14 April 2012 Button Manager SOAP API

Using the Button Manager API

With SO AP

These examples show basic Button Manager API capabilities. The examples show how to create buttons and set inventory levels.

 Specifying HTML Variables  Creating a Button Using SOAP  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 PayPal 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 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_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 (,).

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 cycl e. 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. 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

n) is defined.

Button Manager SOAP API April 2012 15

Using the Button Manager API With SOAP

Creating a Button Using SOAP

HTML Variable Notes

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:

 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 list of HTML variables and complete information, see HTML Variables for

PayPal Payments Standard.

Creating a Button Using SOAP

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

<com.paypal.soap.api.BMCreateBut tonRequestType> <buttonType> <__value__> <m__value>CART</m__value> </__value__> </buttonType> <buttonCode> <__value__> <m__value>HOSTED</m__value > </__value__> </buttonCode> <buttonSubType> <__value__> <m__value>PRODUCTS</m__val ue> </__value__> </buttonSubType> <buttonVar> <string>business=XX-usbiz@paypal. com</string> <string>item_name=Item-123</strin g>

16 April 2012 Button Manager SOAP API

Using the Button Manager API With SOAP

Creating a Button Using SOAP

<string>item_number=#1234</s tring> <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</strin g> </buttonVar>

<optionDetails> <com.paypal.soap.api.Option DetailsType> <optionName>DD1</optionName> <optionSelectionDetails> <com.paypal.soap.api.Optio nSelectionDetailsT ype> <optionSelection>AAAA</o ptionSelection> <price>1.55</price> </com.paypal.soap.api.OptionSelection DetailsType> <com.paypal.soap.api.Optio nSelectionDetailsT ype> <optionSelection>BBBB</o ptionSelection> <price>10.55</price> </com.paypal.soap.api.OptionSelection DetailsType> <com.paypal.soap.api.Optio nSelectionDetailsT ype> <optionSelection>CCCCC</ optionSelection> <price>10.55</price> </com.paypal.soap.api.OptionSelection DetailsType> </optionSelectionDetails> </com.paypal.soap.api.OptionDetai lsType>

<com.paypal.soap.api.Option DetailsType> <optionName>DD2</optionName> <optionSelectionDetails> <com.paypal.soap.api.Optio nSelectionDetailsT ype> <optionSelection>XXXX</o ptionSelection> </com.paypal.soap.api.OptionSelection DetailsType> <com.paypal.soap.api.Optio nSelectionDetailsT ype> <optionSelection>ZZZZ</o ptionSelection> </com.paypal.soap.api.OptionSelection DetailsType> </optionSelectionDetails> </com.paypal.soap.api.OptionDetai lsType> </optionDetails>

Button Manager SOAP API April 2012 17

Using the Button Manager API With SOAP

Tracking Inventory for a Button Using SOAP

<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></buttonLan guage>

</com.paypal.soap.api.BMCreateBu ttonRequestType>

Tracking 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.BMSetInve ntoryRequestType> <hostedButtonID>41</hostedButtonI D> <trackInv>1</trackInv> <trackPnl>1</trackPnl> <itemTrackingDetails> <itemNumber>234234</itemNu mber> <itemQty>10</itemQty> <itemAlert>2</itemAlert> <itemCost>4</itemCost> </itemTrackingDetails> <soldoutURL>http://www.Y ourSoldOutLandingPage.html</soldoutURL> </com.paypal.soap.api.BMSetInv entoryRequestType>

18 April 2012 Button Manager SOAP 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.

 BMCreateButton API Operation  BMUpdateButton API Operation  BMButtonSearch API Operation  BMGetButtonDetails API Operation  BMManageButtonStatus API Operation  BMSetInventory API Operation  BMGetInventory 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.

 BMCreateButton Request  BMCreateButton Response  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 items, each of which can include up to 10 possible selections.

Button Manager SOAP API April 2012 19

Button Manager API Reference

BMCreateButton API Operation

20 April 2012 Button Manager SOAP API

BMCreateButton Request Fields

Field Description

ButtonCode ebl:ButtonCodeType

(Optional) The kind of button code to create. It is one of the following values:

 HO STED - A secure button stored on PayPal; default for all buttons except

View Cart, Unsubscribe, and Pay Now

 EN CRYPTED - An encrypted button, not stored on PayPal; default for View

Cart button

 CL EARTEXT - An unencrypted button, not stored on PayPal; default for

Unsubscribe button

 TO KEN - A secure button, not stored on PayPal, used only to initiate the

Hosted Solution checkout flow; default for Pay Now button. Since version

65.1

ButtonType ebl:ButtonTypeType

(Required) The kind of button you want to create. It is one of the following values:

 BU YNOW - Buy Now button  CA RT - Add to Cart button  GI FTCERTIFICATE - Gift Certificate button  SU BSCRIBE - Subscribe button  DO NATE - Donate button  UN SUBSCRIBE - Unsubscribe button  VI EWCART - View Cart button  PA YMENTPLAN - Installment Plan button; since version 63.0  AU TOBILLING - Automatic Billing button; since version 63.0  PA YMENT - Pay Now button; since version 65.1

NOTE: Do not specify BUYNOW if BUTTONCODE=TOKEN; specify PAYMENT

instead. Do not specify PAYMENT if BUTTONCODE=HOSTED.

Button Manager API Reference

BMCreateButton API Operation

ButtonSubType ebl:ButtonSubTypeType

(Optional) The use of button you want to create. It is one of the following values:

 PR ODUCTS - button is used to purchase products; default for Buy Now and

Add to Cart buttons

 SE RVICES - button is used to purchase services

ButtonVar xs:string

(Optional) HTML standard button variables

Option Details Fields

Field Description

OptionName xs:string

(Optional) The menu name

Button Manager SOAP API April 2012 21

Button Manager API Reference

BMCreateButton API Operation

Field Description

OptionSelectionDetails ns:OptionSelectionDetailsType

(Optional) Menu items

Option Selection Details Fields

OptionSelection xs:string

(Optional) The menu item’s name

Price xs:string

(Optional) The price associated with the first menu item

NOTE: If you specify a price, you cannot set a button variable to amount.

OptionType ebl:OptionTypeListType

(Optional) The installment option type for an OPTION the following values:

 FU LL - Payment in full  VA RIABLE - Variable installments  EM I - Equal installments

NOTE: Only available for Installment Plan buttons.

nNAME, which is one of

PaymentPeriod ns:InstallmentDetailsType

(Optional) Information about an installment option

Installment Details

BillingPeriod ebl:BillingPeriodType

(Optional) The installment cycle unit, which is one of the following values:

 No BillingPeriodType - None (default)  Da y  We ek  Se miMonth  Mo nth  Ye ar

BillingFrequency xs:int

(Optional) The installment cycle frequency in units, e.g. if the billing frequency is 2 and the billing period is Month, the billing cycle is every 2 months. The default billing frequency is 1.

TotalBillingCycles xs:int

(Optional) The total number of billing cycles, regardless of the duration of a cycle; 1 is the default

Amount xs:string

(Optional) The base amount to bill for the cycle.

22 April 2012 Button Manager SOAP API

ShippingAmount xs:string

(Optional) The shipping amount to bill for the cycle, in addition to the base amount.

TaxAmount xs:string

(Optional) The tax amount to bill for the cycle, in addition to the base amount.

Button Language Options

The button language must be compatible with the country identified by the country code.

Country Button Language Options

Button Manager API Reference

BMCreateButton API Operation

All countries not identified below Austria

Belgium

Canada

China (worldwide)

France

Germany

Hong Kong

Italy

Japan

 en - English; default  de - German; default

 en - English  en - English; default

 nl - Dutch  fr - French

 en - English; default  fr - French

 en - English; default  zh - Chinese

 fr - French; default  en - English

 de - German; default  en - English

 zh - Chinese; default  en - English

 it - Italian; default  en - English

 ja - Japanese; default  en - English

Mexico

Netherlands

Poland

Spain

 es - Spanish; default  en - English

 nl - Dutch; default  en - English

 pl - Polish; default  en - English

 es - Spanish; default  en - English

Button Manager SOAP API April 2012 23

Button Manager API Reference

BMCreateButton API Operation

Country Button Language Options

Switzerland

United States

 de - German; default  fr - French  en - English

 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 HTML in a website and for a link in email.

BMCreateButton Response Fields

Field Description

Website xs:string

HTML code for web pages

Email xs:string

Code for email links, links in other documents that support external links, and links to the Hosted Solution checkout flow

24 April 2012 Button Manager SOAP API

Button Manager API Reference

BMCreateButton API Operation

Field Description

HostedButtonID xs:string

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.

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 m ust specify the sam e number of

entries for option prices and selections.

11936 Invalid Data Y ou 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.

Button Manager SOAP API April 2012 25

Button Manager API Reference

BMUpdateButton API Operation

Error Code Short Message Long Message Correcting This Error...

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.

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.

 BMUpdateButton Request  BMUpdateButton Response  BMUpdateButton Errors

26 April 2012 Button Manager SOAP API

BMUpdateButton Request

The hosted button ID identifies the button you want to modify. The remaining request fields specify the characteristics of your button.

Button Manager API Reference

BMUpdateButton API Operation

Button Manager SOAP API April 2012 27

Button Manager API Reference

BMUpdateButton API Operation

BMUpdateButton Request Fields

Field Description

HostedButtonID xs:string

(Required) The ID of the hosted button you want to modify.

ButtonType ebl:ButtonTypeType

(Required) The kind of button you want to update. It is one of the following values:

NOTE: You cannot change the kind of button after the button has been

created.

ButtonCode ebl:ButtonCodeType

(Optional) The kind of button code to create. It is one of the following values:

 HO STED - A secure button stored on PayPal; default for all buttons except

View Cart and Unsubscribe

 EN CRYPTED - An encrypted button, not stored on PayPal; default for View

Cart button

 CL EARTEXT - 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 ebl:ButtonSubTypeType

(Optional) The use of button you want to create. It is one of the following values:

 PR ODUCTS - button is used to purchase products; default for Buy Now and

Add to Cart buttons

 SE RVICES - button is used to purchase services

NOTE: You cannot change the button usage after after the button has been

created.

ButtonVar xs:string

(Optional) HTML standard button variables It is a list of variables, in which

not include leading zeros. Character length and limitations: 63 single-byte alphanumeric characters each

n is a digit between 0 and 999, inclusive; do

28 April 2012 Button Manager SOAP API

Field Description

OptionDetails ns:OptionDetailsType

(Optional) Menu items

TextBox xs:string

(Optional) Text description for a menu item It is a list of variables, in which

ButtonImage ebl:ButtonImageType

(Optional) The kind of button image. It is one of the following values:

 RE G - regular; default  SM L - small  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.

ButtonImageURL xs:string

(Optional) The button’s URL

NOTE: Specify either the kind of button image or the URL.

Button Manager API Reference

BMUpdateButton API Operation

n is a digit between 0 and 1, inclusive.

BuyNowText ebl:BuyNowTextType

(Optional) The button text for a Buy Now button. It is one of the following values:

 BU YNOW - button text is Buy Now; default  PA YNOW - button text is Pay Now

SubscribeText ebl:SubscribeTextType

(Optional) The button text for a Subscribe button. It is one of the following values:

 BU YNOW - button text is Buy Now  SU BSCRIBE - button text is Subscribe; default

ButtonCountry ebl:CountryCodeType

(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

OptionName xs:string

(Optional) The menu name

Button Manager SOAP API April 2012 29

Button Manager API Reference

BMUpdateButton API Operation

Field Description

OptionSelectionDetails ns:OptionSelectionDetailsType

(Optional) Menu items

Option Selection Details Fields

OptionSelection xs:string

(Optional) The menu item’s name

Price xs:string

(Optional) The price associated with the first menu item

NOTE: If you specify a price, you cannot set a button variable to amount.

OptionType ebl:OptionTypeListType

(Optional) The installment option type for an OPTION the following values:

 FU LL - Payment in full  VA RIABLE - Variable installments  EM I - Equal installments

NOTE: Only available for Installment Plan buttons.

nNAME, which is one of

PaymentPeriod ns:InstallmentDetailsType

(Optional) Information about an installment option

Installment Details

BillingPeriod ebl:BillingPeriodType

(Optional) The installment cycle unit, which is one of the following values:

 No BillingPeriodType - None (default)  Da y  We ek  Se miMonth  Mo nth  Ye ar

BillingFrequency xs:int

(Optional) The installment cycle frequency in units, e.g. if the billing frequency is 2 and the billing period is Month, the billing cycle is every 2 months. The default billing frequency is 1.

TotalBillingCycles xs:int

(Optional) The total number of billing cycles, regardless of the duration of a cycle; 1 is the default

Amount xs:string

(Optional) The base amount to bill for the cycle.

30 April 2012 Button Manager SOAP API

ShippingAmount xs:string

(Optional) The shipping amount to bill for the cycle, in addition to the base amount.

TaxAmount xs:string

(Optional) The tax amount to bill for the cycle, in addition to the base amount.

Button Language Options

The button language must be compatible with the country identified by the country code.

Country Button Language Options

Button Manager API Reference

BMUpdateButton API Operation

All countries not identified below Austria

Belgium

Canada

China (worldwide)

France

Germany

Hong Kong

Italy

Japan

 en - English; default  de - German; default

 en - English  en - English; default

 nl - Dutch  fr - French

 en - English; default  fr - French

 en - English; default  zh - Chinese

 fr - French; default  en - English

 de - German; default  en - English

 zh - Chinese; default  en - English

 it - Italian; default  en - English

 ja - Japanese; default  en - English

Mexico

Netherlands

Poland

Spain

 es - Spanish; default  en - English

 nl - Dutch; default  en - English

 pl - Polish; default  en - English

 es - Spanish; default  en - English

Button Manager SOAP API April 2012 31

Button Manager API Reference

BMUpdateButton API Operation

Country Button Language Options

Switzerland

United States

 de - German; default  fr - French  en - English

 en - English; default  fr - French  es - Spanish  zh - Chinese

BMUpdateButton Response

The response contains the hosted button ID, code for HTML in a website, and code for a link in email.

BMUpdateButton Response Fields

Field Description

Website xs:string

HTML code for web pages

Email xs:string

Code for email links and links in other documents that support external links

32 April 2012 Button Manager SOAP API

Button Manager API Reference

BMUpdateButton API Operation

Field Description

HostedButtonID xs:string

ID of a PayPal hosted button

BMUpdateButton 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. 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 m ust specify the sam e number of

entries for option prices and selections. 11936 Invalid Data Y ou 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.

Button Manager SOAP API April 2012 33

Button Manager API Reference

BMButtonSearch API Operation

Error Code Short Message Long Message Correcting This Error...

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. 12210 Invalid Argument The currency code value specified is

BMButtonSearch API Operation

Use the BMButtonSearch API operation to obtain a list of your hosted PayPal Payments Standard buttons.

 BMButtonSearch Request  BMButtonSearch Response  BMButtonSearch Errors

34 April 2012 Button Manager SOAP API

BMButtonSearch Request

The request contains optional fields that are not currently used. All hosted buttons are automatically requested.

Button Manager API Reference

BMButtonSearch API Operation

BMButtonSearch Request Fields

Field Description

StartDate xs:dateTime

(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 xs:dateTime

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

Button Manager SOAP API April 2012 35

Button Manager API Reference

BMButtonSearch API Operation

BMButtonSearch Response

The response contains a list of all hosted buttons and their associated characteristics.

BMButtonSearch Response Fields

Name Description

— ebl:ButtonSearchResult

Search results

ButtonSearchResult

HostedButtonID xs:string

The hosted button ID

HButtonType xs:string

The hosted button ID

ItemName xs:string

The item name

ModifyDate xs:dateTime

The date created or last changed

36 April 2012 Button Manager SOAP 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. 11997 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.

 BMGetButtonDetails Request  BMGetButtonDetails Response  BMUpdateButton Errors

BMGetButtonDetails Request

The request includes only the ID of the hosted button whose details you want to obtain.

Button Manager SOAP API April 2012 37

Button Manager API Reference

BMGetButtonDetails API Operation

BMGetButtonDetails Request Fields

Field Description

HostedButtonID xs:string

BMGetButtonDetails Response

The response fields contain all non-inventory information related to the button.

(Required) The ID of the hosted button whose details you want to obtain.

38 April 2012 Button Manager SOAP API

BMGetButtonDetails Response Fields

Field Description

ButtonType ebl:ButtonTypeType

The kind of button. It is one of the following values:

Button Manager API Reference

BMGetButtonDetails API Operation

ButtonCode ebl:ButtonCodeType

The kind of button code. It is one of the following values:

 HO STED - A secure button stored on PayPal  EN CRYPTED - An encrypted button, not stored on PayPal  CL EARTEXT - An unencrypted button, not stored on PayPal

ButtonSubType ebl:ButtonSubTypeType

The use of button. It is one of the following values:

 PR ODUCTS - button is used to purchase products  SE RVICES - button is used to purchase services

HostedButtonID xs:string

ID of a PayPal hosted button

Website xs:string

HTML code for web pages

Email xs:string

Code for email links and links in other documents that support external links

ButtonVar xs:string

HTML standard button variables

Button Manager SOAP API April 2012 39

Button Manager API Reference

BMGetButtonDetails API Operation

Option Details Fields

Field Description

OptionName xs:string

(Optional) The menu name

OptionSelectionDetails ns:OptionSelectionDetailsType

(Optional) Menu items

Option Selection Details Fields

OptionSelection xs:string

(Optional) The menu item’s name

Price xs:string

(Optional) The price associated with the first menu item

NOTE: If you specify a price, you cannot set a button variable to amount.

OptionType ebl:OptionTypeListType

(Optional) The installment option type for an OPTION the following values:

 FU LL - Payment in full  VA RIABLE - Variable installments  EM I - Equal installments

NOTE: Only available for Installment Plan buttons.

nNAME, which is one of

PaymentPeriod ns:InstallmentDetailsType

(Optional) Information about an installment option

Installment Details

BillingPeriod ebl:BillingPeriodType

(Optional) The installment cycle unit, which is one of the following values:

 No BillingPeriodType - None (default)  Da y  We ek  Se miMonth  Mo nth  Ye ar

BillingFrequency xs:int

(Optional) The installment cycle frequency in units, e.g. if the billing frequency is 2 and the billing period is Month, the billing cycle is every 2 months. The default billing frequency is 1.

40 April 2012 Button Manager SOAP API

Button Manager API Reference

BMManageButtonStatus API Operation

TotalBillingCycles xs:int

(Optional) The total number of billing cycles, regardless of the duration of a cycle; 1 is the default

Amount xs:string

(Optional) The base amount to bill for the cycle.

ShippingAmount xs:string

(Optional) The shipping amount to bill for the cycle, in addition to the base amount.

TaxAmount xs:string

(Optional) The tax amount to bill for the cycle, in addition to the base amount.

BMGetButtonDetails Errors

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

BMManageButtonStatus API Operation

Use the BMManageButtonStatus API operation to change the status of a hosted button. Currently, you can only delete a button.

 BMManageButtonStatus Request  BMManageButtonStatus Response  BMUpdateButton Errors

BMManageButtonStatus Request

The request specifies the hosted button’s ID and the status you want to set the button to.

Button Manager SOAP API April 2012 41

Button Manager API Reference

BMManageButtonStatus API Operation

BMManageButtonStatus Request Fields

Field Description

HostedButtonID xs:string

(Required) The ID of the hosted button whose status you want to change.

ButtonStatus ebl:ButtonStatusType

(Required) The new status of the button. It is one of the following values:

 DE LETE - 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

Error Code Short Message Long Message Correcting This Error...

42 April 2012 Button Manager SOAP API

Button Manager API Reference

BMSetInventory API Operation

Error Code Short Message Long Message Correcting This Error...

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 BMSetInventory 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 inventory, calculate the gross profit associated with sales, send you an alert when inventory drops below a specified quantity, and manage sold out conditions.

 BMSetInventory Request

 BMSetInventory Response  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.

Button Manager SOAP API April 2012 43

Button Manager API Reference

BMSetInventory API Operation

BMSetInventory Request Fields

Field Description

HostedButtonID xs:string

(Required) The ID of the hosted button whose inventory you want to set.

TrackInv xs:string

(Required) Whether to track inventory levels associated with the button. It is one of the following values:

 0 - do not track inventory  1 - track inventory

TrackPnl xs:string

(Required) Whether to track the gross profit associated with inventory changes. It is one of the following values:

 0 - do not track the gross profit  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 BMSetInventory.

— ebl:ItemTrackingDetails

(Optional) Item tracking details for the button

44 April 2012 Button Manager SOAP API

Field Description

OptionIndex xs:string

(Optional) Option index, which identifies the button. Option index 0 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

SoldoutURL xs:string

(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

— ebl:OptionTrackingDetails

(Optional) Option tracking details for menu items associated with the button

ReuseDigitalDownloadKeys xs:string

(Optional) Whether to reuse download keys:

 0 - do not reuse keys (default)  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.

Button Manager API Reference

BMSetInventory API Operation

AppendDigitalDownloadKeysxs:string

(Optional) Whether to append download keys:

 0 - do not append keys (default)  1 - append keys

NOTE: If you do not append the download keys, unused keys will be

replaced..

DigitalDownloadKeys xs:string

(Optional) One or more digital download keys, up to a maximum of 1,000 keys.

Character length and limitations: 1,000 single-byte alphanumeric characters each.

Item Tracking Details Fields

ItemNumber xs:string

(Optional) The ID for an item associated with this button

ItemQty xs:string

The quantity you want to specify for the item associated with this button. Specify either the absolute quantity in this field or the change in quantity in the quantity delta field

Button Manager SOAP API April 2012 45

Button Manager API Reference

BMSetInventory API Operation

ItemQtyDelta xs:string

ItemAlert xs:string

ItemCost xs:string

Option Tracking Details Fields

OptionNumber xs:string

OptionQty xs:string

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

(Optional) The quantity of the item associated with this button below which PayPal sends you an email notification

(Optional) The cost of the item associated with this button

(Optional) The menu item’s ID for an option in a dropdown menu

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

OptionSelect xs:string

(Optional) The menu item’s name in a dropdown menu

OptionQtyDelta xs:string

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 or the absolute quantity in the quantity field

OptionAlert xs:string

(Optional) The quantity of the option associated with this menu item below which PayPal sends you an email notification

OptionCost xs:string

(Optional) The cost of the option associated with this menu item Limitations: Va l ue must be a posit ive num ber, 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.

46 April 2012 Button Manager SOAP API

BMSetInventory Response Fields

Button Manager API Reference

BMSetInventory API Operation

Field Description

TransactionID xs:string

Transaction ID

BMSetInventory Errors

Error 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. 11953 Invalid Data You can only track inventory and profit &

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 specified. 11956 Invalid Argument The TrackInv value specified is invalid. 11957 Invalid Argument The TrackPnl value specified is invalid.

Button Manager SOAP API April 2012 47

Button Manager API Reference

BMSetInventory API Operation

Error Code Short Message Long Message Correcting This Error...

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 & 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 & loss by option. 11970 Invalid Argument Option name index value specified is

invalid. 11971 Invalid Data Inventory and/or profit & loss 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.

48 April 2012 Button Manager SOAP API

Button Manager API Reference

BMSetInventory 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 Y ou 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 & loss by item. 11984 Invalid Argument 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 & 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.

Button Manager SOAP API April 2012 49

Button Manager API Reference

BMGetInventory API Operation

Use the BMGetInventory API operation to determine the inventory levels and other inventory-related information for a button and menu items associated with the button. T ypically, you call BMGetInventory to obtain field values before calling BMSetInventory to change the inventory levels.

 BMGetInventory Request  BMGetInventory Response  BMGetInventory Errors

BMGetInventory Request

The hosted button ID identifies the button whose inventory you want to track.

BMGetInventory Request Fields

Field Description

HostedButtonID xs:string

(Required) The ID of the hosted button whose inventory information you want to obtain.

DigitalDownloadKeys xs:string

(Optional) One or more digital download keys, up to a maximum of 1,000 keys.

Character length and limitations: 1,000 single-byte alphanumeric characters each.

50 April 2012 Button Manager SOAP API

BMGetInventory Response

The response fields contain inventory information related to the button.

Button Manager API Reference

BMGetInventory API Operation

BMGetInventory Response Fields

Field Description

HostedButtonID xs:string

The ID of the hosted button whose inventory you want to set.

TrackInv xs:string

Whether to track inventory levels associated with the button. It is one of the following values:

 0 - do not track inventory  1 - track inventory

Button Manager SOAP API April 2012 51

Button Manager API Reference

BMGetInventory API Operation

Field Description

TrackPnl xs:string

Whether to track the gross profit associated with inventory changes. It is one of the following values:

 0 - do not track the gross profit  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 BMSetInventory.

— ebl:ItemTrackingDetails

Item tracking details for the button

OptionIndex xs:string

Option index, which identifies the button. Option index 0 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

— ebl:OptionTrackingDetails

Option tracking details for menu items associated with the button

SoldoutURL xs:string

The URL to which the buyer’s browser is redirected when the inventory drops to 0

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

ItemNumber xs:string

The ID for an item associated with this button

ItemQty xs:string

The current inventory level of the item associated with this button

ItemQtyDelta xs:string

Not used

ItemAlert xs:string

The quantity of the item associated with this button below which PayPal sends you an email notification

ItemCost xs:string

The cost of the item associated with this button

52 April 2012 Button Manager SOAP API

Option Tracking Details Fields

OptionNumber xs:string

The menu item’s ID for an option in a dropdown menu

OptionQty xs:string

The current inventory level of the option associated with this menu item

OptionSelect xs:string

The menu item’s name in a dropdown menu

OptionQtyDelta xs:string

Not used

OptionAlert xs:string

The quantity of the option associated with this menu item below which PayPal sends you an email notification

OptionCost xs:string

The cost of the option associated with this menu item

Button Manager API Reference

BMGetInventory API Operation

BMGetInventory Errors

Error 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. 11953 Invalid Data You can only track inventory and profit &

loss for buy now, cart or subscription

buttons. 11991 Invalid Data The hosted button id specified does not

have any inventory or cost associated with

it. 11992 Invalid Argument You do not have permissions to access

this button. Please check the hosted button

ID and try again.

Button Manager SOAP API April 2012 53

Button Manager API Reference

BMGetInventory API Operation

54 April 2012 Button Manager SOAP API

HTML Variables for PayPal

Payments Standard

You can use all variables supported for your button: Buy Now, Donation, Subscribe, Add to Cart, and View Cart buttons. You can also use HTML variables supported the Cart Upload command.

Technical HTML Variables

T echnical 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:

 ad d – Add to Cart buttons for the PayPal Shopping Cart  di splay – View Cart buttons for the PayPal Shopping Cart  up load – 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 which kind of button was clicked by decoding the encrypted code or by looking up the saved button in the merchant’s account.

Button Manager SOAP API April 2012 55

HTML Variables for PayPal Payments Standard

Technical HTML Variables

HTML Variables for Special PayPal Features

Required or

Name

Optional Description

Character Length

notify_url Optional The URL to which PayPal posts information about the

payment, in the form of Instant Payment Notification messages.

hosted_button_id See

description.

Required for buttons that have been saved in PayPal accounts; otherwise, not allowed.

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:

Substitute <Service> with an appropriate value from the following list:

 B uyNow  A ddToCart  D onate  S ubscribe  A utomaticBilling  I nstallmentPlan  B uyGiftCertifcate  S hoppingCart

Substitute <Product> with WPS always for Website Payments Standard payment buttons and for the Website Payments Standard Cart Upload command.

Substitute <Country> 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_U S"

255

See description.

NOTE: HTML button code that you create on the PayPal

website includes bn variables with valid values generated by PayPal.

56 April 2012 Button Manager SOAP API

HTML Variables for PayPal Payments Standard

HTML Variables for Individual Items

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

Name

Optional Description

HTML Variables for Individual Items

Character Length

amount See

description.

discount_amount Optional Discount amount associated with an item .

discount_amount2 Optional Discount amount associated with each additional quantity of

discount_rate Optional Discount rate (percentage) associated with an item.

The price or amount of the product, service, or contribution, 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.

 Required for Add to Cart buttons  Optional for Buy Now and Donate buttons  Not us ed with Subscribe or Buy Gift Certificate buttons

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 quantity of items purchased.

Valid only fo r Buy Now and Add to Cart buttons.

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 0 for discount_amount2 to take effect.

Valid only fo r Buy Now and Add to Cart buttons.

It must be set to a value less than 100. If you do not set discount_rate2, the value in discount_ra te applies only to the first item regardless of the quantity of items purchased.

Valid only fo r 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 fo r Buy Now and Add to Cart buttons.

Button Manager SOAP API April 2012 57

HTML Variables for PayPal Payments Standard

HTML Variables for Individual Items

Required or

Name

Optional Description

discount_num Optional Number of additional quantities of the item to whic h the

discount applies. Applicable when you use discount_amount2 or

discount_rate2. Use this variable to specify an upper limit on the number of discounted items.

Valid only fo r Buy Now and Add to Cart buttons.

Character Length

item_name See

description.

Description of item. If this variable is omitted, buyers enter their own name during checkout.

 Optional for Buy Now, Donate, Subscribe, Automatic

Billing, Installment Plan, and Add to Cart buttons

 Not used with Buy Gift Certificate buttons

item_number See

description.

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.

quantity Optional 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.

shipping Optional 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 val id onl y for Bu y Now and Add

to Cart buttons. Default – If profile-based shipping rates are configured,

buyers are charged an amount according to the shipping methods they choose.

127

shipping2 Optional 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 val id onl y for Bu y Now and Add to Cart buttons.

58 April 2012 Button Manager SOAP API

HTML Variables for PayPal Payments Standard

HTML Variables for Individual Items

Required or

Name

tax Optional Transaction-based tax override variable. Set this variable to a

Optional Description

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.

Character Length

tax_rate Optional Transaction-based tax override variable. Set this variable to a

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_ quantity

Optional 1 – allows buyers to specify the quantity.

 Optional for Buy Now buttons  Not used with other buttons

weight Optional Weight of items. If profile-based shipping rates are

configured with a basis of weight, 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:

 lbs  kgs

The default is lbs.

on0 Optional First option field name and label. The os0 variable contains

the corresponding value for this option field. For example, if on0 is size, os0 could be large.

 Optional for Buy Now, Add to Cart, Subscribe,

Automatic Billing, and Installment Plan buttons

 Not used with Donate or Buy Gift Certificate buttons

on1 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).

 Optional for Buy Now, Add to Cart, Subscribe,

Automatic Billing, and Installment Plan buttons

 Not used with Donate or Buy Gift Certificate buttons

Button Manager SOAP API April 2012 59

HTML Variables for PayPal Payments Standard

HTML Variables for Individual Items

Required or

Name

Optional Description

Character

Length

os0 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 allowable value should be no more than 64 characters. If buyers enter this value in a text field, there is a 200character 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:

<option value="small">small - $10.00</option>

Add a corresponding option_select0 and option_amount0 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.

 Optional for Buy Now, Add to Cart, Subscribe,

Automatic Billing, and Installment Plan buttons

 Not used with Donate or Buy Gift Certificate buttons

os1 Optional Option selection of the buyer for the second option field,

on1. 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 os6). 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.

 Optional for Buy Now, Add to Cart, Subscribe,

Automatic Billing, and Installment Plan buttons

 Not used with Donate or Buy Gift Certificate buttons

See

description.

64 or 200

See

description.

60 April 2012 Button Manager SOAP API

Name

HTML Variables for PayPal Payments Standard

Required or Optional Description

HTML Variables for Individual Items

Character

Length

option_index See

description.

The cardinal number of the option field, on0 through on9, that has product options with different prices for each option. Include option_index if the option field with prices is not on0.

 Optional for Buy Now, Add to Cart, Subscribe,

Automatic Billing, and Installment Plan buttons

 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

the on0 dropdown menu. The values must match exactly, as the following sample code shows:

<option value="small">small - $10.00</option> ... <input type="hidden" name="option_select0" value="small">

 Optional for Buy Now, Add to Cart, Subscribe,

Automatic Billing, and Installment Plan buttons

 Not used with Donate or Buy Gift Certificate buttons

option_amount0 Optional For priced options, the amount that you want to charge for

the first option selection of the on0 dropdown menu. Use only numeric values; the currency is taken from the currency_code variable. For example:

<option value="small">small - $10.00... <input type="hidden" name="option_amount0"</option> value="10.00">

 Optional for Buy Now, Add to Cart, Subscribe,

Automatic Billing, and Installment Plan buttons

 Not used with Donate or Buy Gift Certificate buttons

Button Manager SOAP API April 2012 61

HTML Variables for PayPal Payments Standard

HTML Variables for Payment Transactions

Required or

Name

Optional Description

Character

Length

option_select1 Optional For priced options, the value of the second option sel ection

of the on0 dropdown menu. For example:

... <option value="medium">small $10.00</option>... <input type="hidden" name="option_select" value="medium">

You can specify a maximum of 10 option selections by incrementing the option selection index (option_select0 through option_select9).

NOTE: A corresponding option selection in os0 must also

be set.

 Optional for Buy Now, Add to Cart, Subscribe,

Automatic Billing, and Installment Plan buttons

 Not used with Donate or Buy Gift Certificate buttons

option_amount1 Optional For priced options, the amount that you want to charge for

the second option selection of the on0 dropdown menu. For example:

... <option value="small">medium - $15.00</option> ... <input type="hidden" name="option_amount1" value="15.00">

Yo u can sp ecify a maximum of 10 option amounts by incrementing the option amount index (option_amount0 through option_amount9).

NOTE: A corresponding option selection in os0 must also

be set.

 Optional for Buy Now, Add to Cart, Subscribe,

Automatic Billing, and Installment Plan buttons

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

62 April 2012 Button Manager SOAP API

HTML Variables for Payment Transactions

Required or

Name

Optional Description

HTML Variables for PayPal Payments Standard

HTML Variables for Shopping Carts

Character

Length

address_ override

currency_code Optional The currency of the payment. The default is USD. 3 custom Optional Pass-through variable for your own tracking purposes, which

handling Optional Handling charges. This variable is not quantity-specific. The

invoice Optional Pass-through variable you can use to identify your invoice

tax_cart Optional Cart-wi de tax, overriding any individual item tax_ weight_cart Optional If profile-based shipping rates are configured with a basis of

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

buyers do not see. Default – No variable is passed back to you.

same handling cost applies, regardless of the number of items on the order.

Default – No handling charges are included.

number for this purchase. Default – No variable is passed back to you.

x value

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.

256

127

weight_unit Optional The unit of measure if weight_cart is specified.

Allowable values are:

 lbs  kgs

The default value is lbs.

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 SOAP API April 2012 63

HTML Variables for PayPal Payments Standard

HTML Variables for Shopping Carts

Required or

Name

Optional Description

Character

Length

add See

description.

Add an item to the PayPal Shopping Cart. 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 associated 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 _cart

Optional Single discount amount charged cart-wide.

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

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 art

Optional Single discount rate (percentage) to be charged cart-wide.

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

Applies only to the Cart Upload command.

display See

description.

Display the contents of the PayPal Shopping Cart to the 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 both add and display are specified, display takes precedence.

64 April 2012 Button Manager SOAP API

HTML Variables for PayPal Payments Standard

HTML Variables for Recurring Payments Buttons

Required or

Name

handling_ cart Optional Single handling fee charged cart-wide. If handling_cart

Optional Description

is used in multiple Add to Cart buttons, the handling_cart value of the first item is used.

Character

Length

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:

 sale  authorization  order

The default value is sale. Set the value to authorizatio n 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: If you set paymentaction to order, use

the Authorization & 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

description

Upload the contents of a third-party shopping cart or a 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:

 Subscribe buttons  Automatic Billing buttons

Button Manager SOAP API April 2012 65

HTML Variables for PayPal Payments Standard

HTML Variables for Recurring Payments Buttons

 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

Name

business Required Your PayPal ID or an email address associated with your

Optional Description

PayPal account. Email addresses must be confirmed.

Character

Length

item_name Optional Description of item being sold. If you are collecting

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.

The default is USD.

a1 Optional Trial period 1 price. For a free trial period, specify 0. p1 See

description.

Trial period 1 duration. Required if you specify a1. Specify an integer value in the allowable range for the units of duration that you specify with t1.

t1 See

description.

Trial period 1 units of duration. Required if you specify a1. Allowable values are:

 D – for days; allowable range for p2 is 1 to 90  W – for weeks; allowable range for p2 is 1 to 52  M – for months; allowable range for p2 is 1 to 24  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

a1.

p2 See

description.

Trial period 2 duration. Required if you specify a2. Specify an integer value in the allowable range for the units of duration that you specify with t2.

127

t2 See

description.

Trial period 2 units of duration. Allowable values are:

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.

66 April 2012 Button Manager SOAP API

Name

HTML Variables for PayPal Payments Standard

Required or Optional Description

HTML Variables for Recurring Payments Buttons

Character

Length

t3 Required Regular subscription units of duration.

Allowable values are:

 D – for days; allowable range for p3 is 1 to 90  W – for weeks; allowable range for p3 is 1 to 52  M – for months; allowable range for p3 is 1 to 24  Y – for years; allowable range for p3 is 1 to 5

src Optional Recurring payments. Subscription payments reoccur unless

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:

 0 – subscription payments do not recur  1 – subscription payments recur

The default is 0.

srt Optional Recurring times. Number of times that subscription

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

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 I-), the profile is suspended after the attempt instead of cancelled.

Allowable values are:

 0 – do not reattempt failed recurring payments  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:

 1 – 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. Subscribers 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 SOAP API April 2012 67

HTML Variables for PayPal Payments Standard

HTML Variables for Recurring Payments Buttons

Required or

Name

Optional Description

Character

Length

modify Optional Modification behavior.

Allowable values are:

 0 – allows subscribers only to sign up for new

subscriptions

 1 – allows subscribers to sign up for new subscriptions

and modify their current subscriptions

 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

passwords for subscribers.

Automatic Billing Button HTML Variables

Required or

Name

Optional Description

max_text Optional A descriptio n of the automatic billing plan. The button

creation tool uses the same value that you enter in the Description field. Your bu tton 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.

Character

Length

set_customer_li mit

Required Specify whether to let buyers enter maximum billing limits

in a text box or choose from a list of maximum billing limits that you specify.

Allowable values are:

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

 max_limit_defined – your button displays a

dropdown menu of product options with prices to let buyers choose their maximum billing limits.

min_amount Optional The minimum monthly billing limit, if you have one. Valid

only if set_customer_limit = max_limit_own.

68 April 2012 Button Manager SOAP API

Installment Plan Buttons HTML Variables

Required or

Name

Optional Description

HTML Variables for PayPal Payments Standard

HTML Variables for Recurring Payments Buttons

Character

Length

disp_tot Optional Display the to tal payment amount to buyers during checkout

Allowable values are:

 Y – display the total  N – do not display the total

The default is N.

option_index Required

 If the button offers a single plan, use 0, or use a number

not used for option fields without prices, such as size and color.

 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_select

n Required  If the button offers a single plan, the value attribute of a

hidden input field named os

n. The value attributes of

both elements must match, as the following sample code shows

 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:

<input type="radio" name="osn" value="pay-in-4">Pay in 4 installments ... <input type="hidden" name="option_selectn" value="pay-in-4">

option_select name

Required  If the button offers plan options, text next to the radio

button for plan option

 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 SOAP API April 2012 69

HTML Variables for PayPal Payments Standard

HTML Variables for Recurring Payments Buttons

Required or

Name

Optional Description

Character

Length

option_selectn_ type

option_select a

option_select p

option_select t

option_select n

Required Whether the single plan or plan option n offered by the

button is paid in full, in equal periods, or in variable periods Allowable values are:

 F – pay in full, at checkout  E – pay in equal periods, beginning at checkout or

sometime later

 V – pay in variable periods, beginning at checkout

Required Amoun t of paym ent m.

If the value of option_select

n_type is E, the value of

this variable applies to all payments in the plan.

Required Duration of pay ment pe rio d m. Specify the numb er of time

units with option_selectn_tm. If the value of option_select

n_type is E, the value of

this variable applies to all payments in the plan.

Required Units of time for payment period

Allowable values are:

Required. Number of payments that are the same, in amount and

duration, as this one.

 If the value of option_selectn_type is F, set the

value to 1.

 If the value of option_selectn_type is E, set the

value to the number of payments in the plan.

 If the value of option_selectn_type is F and no

subsequent payments are the same as this one, set the value to 1.

70 April 2012 Button Manager SOAP API

HTML Variables for PayPal Payments Standard

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

Name

or Optional Description

Character

Length

page_style Optional The custom payment page style for checkout pages.

Allowable values are:

 paypal – use the PayPal page style  primary – use the page style that you marked as

primary in your account profile

 page_style_name – use the custom payment page

style from your account profile that has the specified name

The default is 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

in the upper left corner of the PayPal checkout pages. Default – Your business name, if yo u have a PayPal

Business account, or your email address, if you have PayPal Premier or Personal account.

cpp_cart_border _color

Optional The HTML hex code for your principal identifying 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.

 Valid only for Buy Now and Add to Cart buttons and the

Cart Upload command.

 Not used with Subscribe, Donate, or Buy Gift Certificate

buttons.

1,024

cpp_header_ image

Optional The image at the top left of the checkout page. The image’s

maximum size is 750 pixels wide by 90 pixels high. PayPal

No limit

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 SOAP API April 2012 71

HTML Variables for PayPal Payments Standard

HTML Variables for Displaying PayPal Checkout Pages

Required or

Name

Optional Description

Character

Length

cpp_ headerback_ color

Optional The background color for the header of the checkout page.

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_ headerborder_co lor

Optional The border color around the header of the checkout page.

The border is a 2-pixel perimeter around the header space, 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,

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 nonsecure items.

Valid value is 127 sing le-b yte alphanumeric characters

 Valid only for Buy Now and Add to Cart buttons and the

Cart Upload command.

 Not used with Subscribe, Donate, or Buy Gift Certificate

buttons.

127

cpp_payflow_ color

Optional The background color for the checkout page below the

header. Valid value is case-insensitive six-character, HTML

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

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

72 April 2012 Button Manager SOAP API

Name

HTML Variables for PayPal Payments Standard

HTML Variables for Displaying PayPal Checkout Pages

Required or Optional Description

Character

Length

no_note Optional Do not prompt buyers to include a note with their payments.

Allowable values are:

 0 – provide a text box and prompt for the no te  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

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.

Allowable values are:

 0 – prompt for an address, but do not require one  1 – do not prompt for an address  2 – prompt for an address, and require one

The default is 0.

return Optional The URL to which PayPal redirects buyers’ browser after

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.

1,024

rm Optional Return method. The FORM METHOD used to send data to the

1 URL specified by the return variable.

Allowable values are:

 0 – all shopping cart payments use the GET method  1 – the buyer’s browser is redirected to the return URL

by using the GET method, but no payment variables are included

 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 SOAP API April 2012 73

HTML Variables for PayPal Payments Standard

HTML Variables for Filling Out PayPal Checkout Pages Automatically

Required or

Name

Optional Description

Character

Length

cbt Optional Sets the text for the Return to Merchant button on the

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_return Optional A URL to which PayPal redirects the buyers’ browsers if

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.

1,024

NOTE: When you pass in address_override=1 or tax or shipping variables, PayPal

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.

HTML Variables for Filling Out PayPal Checkout Pages Automatically for Buyers

Required or

Name

address1 Optional Street (1 of 2 fields) 100 address2 Optional Street (2 of 2 fields) 100 city Optional City 40 country Optional Sets shipping and billing count ry. 2 email Optional Email address 127 first_name Optional First name 32 last_name Optional Last name 64

74 April 2012 Button Manager SOAP API

Optional Description

Character

Length

Name

HTML Variables for PayPal Payments Standard

Required or Optional Description

HTML Variables for the Instant Update API

Character

Length

lc Optional Sets the language for the billing information/log-in page

only. The default is US.

charset Optional Sets the character set and character encoding for the billin g

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

for phone numbers outside the U.S. PayPal fills in the buyer’s home phone number automatically.

night_ phone_b Optional The three-digit prefix for U.S. phone numbers, or the entire

phone number for phone numbers outside the U.S., 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.

PayPal fills in the buyer’s home phone number automatically.

state Optional State code 2 zip Optional Postal code 32

See

description.

See

description.

See

description.

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 callback 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 SOAP API April 2012 75

HTML Variables for PayPal Payments Standard

HTML Variables for the Instant Update API

HTML Variables to Set Up an Instant Update Payment

Required or

Name

Optional Description

callback_url Required The URL of your Instant Update callback server 1024

Character

Length

callback_timeout 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 Y our 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..

callback_version Optional The version of the Instant Update API that your callback

server uses. The default is the current version.

fallback_tax_am ount

fallback_shippi ng_option_name_

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”. You 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_defa ult_x with its index (

x) set to 0 and its value set to 1.

Allowable values for

x are 0-9.

fallback_shippi ng_option_amoun t_

fallback_shippi ng_option_is_de fault_

Required Shipping amount for optio n

response times out. Allowable values for

Required Indicates that shipping option

selected in the dropdown menu as a fallback, if the response times out.

x to use as a fallback, if the

x are 0-9.

x is the default and should be

Only one shipping option can be the default for buyers. Check that you set 1 instance only of fallback_shipping_option_is_defa ult_x to the value 1.

Allowable values are:

 1 – shipping option x is the default shipping option  0 – shipping option x is not the default shipping option

Allowable values for

x are 0-9.

76 April 2012 Button Manager SOAP API

Name

HTML Variables for PayPal Payments Standard

Required or Optional Description

HTML Variables for the Instant Update API

Character

Length

fallback_insura nce_option_offe red

fallback_insura nce_amount

Optional Indicates that insurance is offered. PayPal ignores this

HTML variable if fallback_ insurance_amount is omitted or the value is 0 or less.

Allowable values are:

 1 – insurance is offered  0 – insurance is not offered

Optional Insurance amount to use as a fallback, if the callback

response times out. Include the fallback_insurance_option_offere d 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

Name

or Optional Description

Character

Length

height_

height_unit Optional Unit of measure for the values specified by the height_x

width_

width_unit Optional Unit of measure for the value specified by width_x

length_

x Optional Height of item x in the shopping cart.

Allowable values are positive integers.

values. Allowable values are any values that you choose to provide.

PayPal passes the value to your callback server in callback requests.

x Optional Width of item x in the shopping cart.

Allowable values are positive integers.

Allowable values are any values that you choose to provide. PayPal passes the value to your callback server in callback requests.

x Optional Length of item x in the shopping cart.

Allowable values are positive integers.

Button Manager SOAP API April 2012 77

HTML Variables for PayPal Payments Standard

HTML Variables for the Instant Update API

Required or

Name

length_unit Optional Unit of measure for the value specified by length_x

Optional Description

Allowable values are any values that you choose to provide. PayPal passes the value to your callback server in callback requests.

Character

Length

78 April 2012 Button Manager SOAP API

PayPal Website Payments Standard - 2012 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Preface

Intended Audience

Revision History

PayPal Payments Standard Button Manager API Overview

Button Manager Introduction

Generated Button Code

Button Hosting

Hosted Button Manipulation

Inventory Management Using Hosted Buttons

Inventory Management for Digital Downloads

Button Manager API Summary

Hosted Solution Links

Granting Third-Party Permission for APIs

Specifying HTML Variables

Creating a Button Using SOAP

Tracking Inventory for a Button Using SOAP

Button Manager API Reference

BMCreateButton API Operation

BMCreateButton Request

BMCreateButton Response

BMCreateButton Errors

BMUpdateButton API Operation

BMUpdateButton Request

BMUpdateButton Response

BMUpdateButton Errors

BMButtonSearch API Operation

BMButtonSearch Request

BMButtonSearch Response

BMGetButtonDetails API Operation

BMButtonSearch Errors

BMGetButtonDetails Request

BMGetButtonDetails Response

BMManageButtonStatus API Operation

BMGetButtonDetails Errors

BMManageButtonStatus Request

BMManageButtonStatus Response

BMManageButtonStatus Errors

BMSetInventory API Operation

BMSetInventory Request

BMSetInventory Response

BMSetInventory Errors

BMGetInventory API Operation

BMGetInventory Request

BMGetInventory Response

BMGetInventory Errors

Technical HTML Variables

HTML Variables for Individual Items

HTML Variables for Payment Transactions

HTML Variables for Shopping Carts

HTML Variables for Recurring Payments Buttons

HTML Variables for Displaying PayPal Checkout Pages

HTML Variables for Filling Out PayPal Checkout Pages Automatically

HTML Variables for the Instant Update API