BMCreateButton API Operation (NVP)

Creates a PayPal Payments Standard button. You can create either a button that is hosted on PayPal or a non-hosted button.

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.

BMCreateButton Request Fields

Field

Description

METHOD

(Required) BMCreateButton

BUTTONCODE

(Optional) The kind of button code to create. Value is:


  • HOSTED. A secure button stored on PayPal; default for all buttons except View Cart, Unsubscribe, and Pay Now

  • ENCRYPTED. An encrypted button, not stored on PayPal; default for View Cart button

  • CLEARTEXT. An unencrypted button, not stored on PayPal; default for Unsubscribe button

  • TOKEN. 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

(Required) The kind of button you want to create. Value is:


  • BUYNOW. Buy Now button

  • CART. Add to Cart button

  • SUBSCRIBE. Subscribe button

  • DONATE. Donate button

  • UNSUBSCRIBE. Unsubscribe button

  • VIEWCART. View Cart button

  • PAYMENTPLAN. Installment Plan button; since version 63.0

  • AUTOBILLING. Automatic Billing button; since version 63.0

  • PAYMENT. 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.

BUTTONSUBTYPE

(Optional) The use of button you want to create. Value is:


  • PRODUCTS. button is used to purchase products; default for Buy Now and Add to Cart buttons

  • SERVICES. button is used to purchase services

L_BUTTONVARn

(Optional) HTML standard button variables

Option Details Fields

Field

Description

OPTIONnNAME

(Optional) The menu name

It is one or more variables, in which n is a digit between 0 and 4, inclusive, for hosted buttons; otherwise, it is a digit between 0 and 9, inclusive.

Option Selection Details Fields

L_OPTIONnSELECTx

(Optional) The menu item name.

A list of variables for each OPTIONnNAME, where x is a digit between 0 and 9, inclusive.

L_OPTION0PRICEx

(Optional) The price associated with the first menu item.

List of variables for each OPTION0NAME, where x is a digit between 0 and 9, inclusive.

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

OPTIONnTYPE

(Optional) The installment option type for an OPTIONnNAME, which is one of the following values:

  • FULL. Payment in full.

  • VARIABLE. Variable installments.

  • EMI. Equal installments.

Note: Only available for Installment Plan buttons.

Installment Details

L_OPTIONnBILLINGPERIODx

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

  • NoBillingPeriodType. None (default).

  • Day

  • Week

  • SemiMonth

  • Month

  • Year

List of variables for each OPTIONnNAME, where x is a digit between 0 and 4, inclusive

L_OPTIONnBILLINGPFREQUENCYx

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

List of variables for each OPTIONnNAME, in which x is a digit between 0 and 4, inclusive

L_OPTIONnTOTALBILLINGCYCLESx

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

List of variables for each OPTIONnNAME, in which x is a digit between 0 and 4, inclusive

L_OPTIONnAMOUNTx

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

List of variables for each OPTION0NAME, in which x is a digit between 0 and 4, inclusive

L_OPTIONnSHIPPINGAMOUNTx

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

List of variables for each OPTION0NAME, in which x is a digit between 0 and 4, inclusive

L_OPTIONnTAXAMOUNTx

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

List of variables for each OPTION0NAME, in which x is a digit between 0 and 4, inclusive

Button Language Options

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

Country

Button Language Options

All countries not identified below

  • en. English; default.

Austria

  • de. German; default.

  • en. English.

Belgium

  • en. English; default.

  • nl. Dutch.

  • fr. French.

Canada

  • en. English; default.

  • fr. French.

China (worldwide)

  • en. English; default.

  • zh. Chinese.

France

  • fr. French; default.

  • en. English.

Germany

  • de. German; default.

  • en. English.

Hong Kong

  • zh. Chinese; default.

  • en. English.

Italy

  • it. Italian; default.

  • en. English.

Japan

  • ja. Japanese; default.

  • en. English.

Mexico

  • es. Spanish; default.

  • en. English.

Netherlands

  • nl. Dutch; default.

  • en. English.

Poland

  • pl. Polish; default.

  • en. English.

Spain

  • es. Spanish; default.

  • en. English.

Switzerland

  • de. German; default.

  • fr. French.

  • en. English.

United States

  • 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

WEBSITECODE

HTML code for web pages

EMAILLINK

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

HOSTEDBUTTONID

ID of a PayPal-hosted button or a Hosted Solution token.

BMCreateButton Errors

Error code Short and long messages User action
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.
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 must specify the same number of entries for option prices and selections.
11936 Invalid Data
You 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.
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.