100,076 downloads

Thanks for all the love! :)

WordPress Nice PayPal Button Documentation

Basic Usage

Shortcode Attributes

Shortcode Attribute Definitions

Plugin Options

Basic Usage

Usage is simple. Create a new post or page add your content to it. Wherever you want a PayPal button to appear include a shortcode like the following example. When you view your published post or page the shortcode will be automatically replaced with a corresponding PayPal button.

 

Shortcode Example

[nicepaypal type="cart" name="WordPress Coffee Mug" amount="12.50"]

 

Shortcode Syntax

[nicepaypal attribute_name="attribute_value"]

^top

 

Shortcode Attributes

The Nice PayPal Button plugin provides a number of options through the inclusion of 8 shortcode attributes. These attributes are as follows.

  • type
  • custom_button
  • amount
  • name
  • sku
  • shipping
  • shipping2
  • handling
  • surcharge
  • surcharge_description
  • tax
  • tax_rate
  • quantity
  • weight
  • button_language
  • country_code
  • currency_code
  • option1
  • option2
  • option3
  • option4
  • option5
  • option6
  • option7
  • option8
  • option9
  • return_url
  • cancel_url
  • hosted_button_id
  • encrypted

Each attribute can be set in the shortcode by including the attribute name followed by an equals sign and the attribute value in quotes.

 

Attribute Example

[nicepaypal name="WordPress Coffee Mug" amount="12.50" shipping="4.95"]

^top

 

Shortcode Attribute Definitions

type

 

[nicepaypal type="button_type"]

Select between the different button operational types; the Buy Now button, the PayPal Pay Now button, the PayPal Donation button, the PayPal Cart button,  the PayPal View Cart button and the PayPal Hosted button. If omitted the plugin will default to use the “Buy Now” button.

Valid entries are “buy”, "pay", “donate”, “cart”, "cart-view", "cart_view", "hosted", "hosted-buy", "hosted-pay", "hosted-donate", "hosted-cat", and "hosted-cart-view".

 

Examples

Buy Now button: [nicepaypal type="buy"]

Pay Now button: [nicepaypal type="pay"]

Donation button: [nicepaypal type="donate"]

Add to Cart button: [nicepaypal type="cart"]

View Cart button: [nicepaypal type="cart-view"]

^top

 

 

custom_button

 

[nicepaypal custom_button="url_value"]

You may desire to use your own custom button graphic in place of the standard PayPal button graphic. In which case, you only need to add the URL of your custom graphic to the shortcode using the custom_button attribute.

Example

Donate with standard PayPal button art:

[nicepaypal type="donate" amount="10.00" name="Feed the Children"]

 

Donate with custom button art:

[nicepaypal type="donate" amount="10.00" name="Feed the Children" custom_button="http:/www.domain.com/images/customdonatebutton.jpg"]

 

^top

 

name

[nicepaypal name="Item Name"]

The name of the item being sold. If omitted, payers enter their own name at the time of payment.

^top

 

amount

 

[nicepaypal amount="0.00"]

The price or amount of the product, service, or contribution, not including shipping & handling, or tax. If omitted from Buy Now payers enter their own amount during checkout on the PayPal payment page.

*IMPORTANT:* Do not enter a currency symbol, just the numerical amount.

 

Amount Text Input Field

To display an amount text input field, which will allow the buyer to enter their own amount, use the following syntax.

 

Syntax

[nicepaypal amount="type;label;default value;field size]

 

Examples

[nicepaypal amount="field"]

[nicepaypal amount="field;Enter Amount"]

[nicepaypal amount="field;Enter Amount;14.00"]

[nicepaypal amount="field;Enter Amount;14.00;5"]

[nicepaypal amount="field;Enter Amount;;5"]

 

^top

 

sku

[nicepaypal sku="000"]

The id number or sku number for your item. A pass-through variable for you to track product or service purchased or the contribution made. The value you specify passed back to you upon payment completion.

^top

 

shipping

[nicepaypal shipping="0.00"]

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.

Default – If profile-based shipping rates are configured, buyers are charged an amount according to the shipping methods they choose.

^top

 

shipping2

[nicepaypal shipping2="0.00"]

The cost of shipping each additional unit of this item. If omitted and profile-based shipping rates are configured, buyers are charged an amount according to the shipping methods they choose.

^top

 

 

handling

[nicepaypal handling="0.00"]

Single handling fee charged cart-wide or one time for buy now items (regardless of quantity). If handling is used in multiple Add to Cart buttons, the handling value of the first item is used.

^top

 

surcharge

[nicepaypal surcharge="0"]

This optional attribute will allow you to automatically include a percentage based surcharge to your item price. Enter your percentage without the precentage symbol. Example 3% would be entered as 3. Enter 0 to exlcude a surcharge set in the plugin admin options.

^top

 

surcharge_description

[nicepaypal surcharge_description="Surcharge Description"]

This attribute automatically appends the item name with a description of the surcharge. Example, if your are selling a WordPress Coffee Mug with a 3% surcharge, you might enter something like "- Price includes a 3% surcharge." The resulting item name will be: WordPress Coffee Mug - Price includes a 3% surcharge.

^top

 

tax

[nicepaypal tax="0.00"]

Transaction-based tax override variable. Set this to a flat tax to the transaction regardless of the buyer’s location. This value overrides any tax settings set in your account profile.

Default – PayPal profile tax settings, if any, apply. To use your PayPal account tax settings simply exclude the tax attribute.

^top

 

tax_rate

[nicepaypal tax_rate="0"]

Transaction-based tax override variable. Set this to a percentage based tax to the transaction regardless of the buyer’s location. This value overrides any tax settings set in your PayPal account profile.

Default – PayPal profile tax settings, if any, apply.

To use your PayPal account tax settings simply exclude the tax_rate attribute.

^top

 

 

quantity

[nicepaypal quantity="0"]

The number of items or item quantity included in the purchase. For example, if you wanted to sell 10 golf balls at once, you would set the item quantity to 10.

 

 

Quantity Text Input Field

To display a quantity text input field, which will allow the buyer to enter their own quantity, use the following syntax.

 

Syntax

[nicepaypal quantity="type;label;default value;field size]

 

Examples

[nicepaypal quantity="field"]

[nicepaypal quantity="field;Enter Quantity"]

[nicepaypal quantity="field;Enter Quantity;10"]

[nicepaypal quantity="field;Enter Quantity;10;5"]

[nicepaypal quantity="field;Enter Quantity;;5"]

^top

 

weight

[nicepaypal weight="0.0"]

The weight of the item. If PayPal account based shipping rates are configured with a basis of weight, the sum of weight values is used to calculate the shipping charges for the transaction. To enable PayPal account based shipping exclude the shipping and shipping2 attributes. After which you can optionally specify a item weight by entering a numerical (float) weight value, e.g. 1.5.

You may specify pounds or kilograms by adding a suffix of lbs or kgs to your weight value. If no suffix is provided the units of weight will default to pounds.

 

Example

[nicepaypal weight="1.5kgs"]

^top

 

button_language

[nicepaypal button_language="value"]

By default the Nice PayPal Button uses the button langage settings from the Administrator Options. However, if you would like to override the default settings on for an individual button, you can do so by setting the button_language attribute.

 

Example

[nicepaypal button_language="fr_FR"]

[nicepaypal button_language="de_DE"]

^top

 

country_code

[nicepaypal country_code="value"]

By default the Nice PayPal Button uses the country code settings from the Administrator Options. However, if you would like to override the default settings on for an individual button, you can do so by setting the country_code attribute.

 

Examples

[nicepaypal country_code="FR"]

[nicepaypal country_code="DE"]

^top

 

currency_code

[nicepaypal currency_code="value"]

By default the Nice PayPal Button uses the currency code settings from the Administrator Options. However, if you would like to override the default settings on for an individual button, you can do so by setting the currency_code attribute.

 

Examples

[nicepaypal currency_code="EUR"]

[nicepaypal currency_code="GBP"]

*IMPORTANT: PayPal does not allow mixed currency codes in the PayPal hosted Shopping Cart. You need to restrict the usage of this setting to "Buy Now" and "Pay Now" button types only.

^top

 

option1 - option9

The option attributes allow you to add text input fields, drop down option menus and price altering drop down menus to your PayPal purchase buttons. PayPal allows you to include up to 9 optional fields with any one purchase button. In turn, the Nice PayPal Button plugin includes the attributes option1 through option9. You will need to use the correct syntax for the attribute values.

 

Text Input

To specify a text input options field you need to utilize a sub-syntax as the attributes value.

[nicepaypal option1="type;name;label;size"]

 

Example

[nicepaypal option="field;size;Enter your size;5"]

 

Drop Down Menu

To specify a drop down menu you need to utilize a sub-syntax as as the attributes value.

[nicepaypal option1="type;name;label;option_value;option_value;option_value]

 

Example

[nicepaypal option1="drop;color;Select t-shirt color;Red;Blue;White;Black"]

 

*Note, you may enter as many "option values" as you need. For example, if you need to offer 3 different shirt colors, you could set a syntaxt that looks like the following.

[nicepaypal option1="drop;color;Select t-shirt color;Red;Blue;White"]

 

Alternatively, if you wanted to offer six shirt colors you might have a syntax like the following.

[nicepaypal option1="drop;color;Select t-shirt color;Red;Blue;White;Black;Green;Yellow"]

 

Price Altering Drop Down Menus

*IMPORTANT: PayPal only allows product price alterations to be be effected by one attribute per product.

There are two option attribute types, which are used to alter an item's price based on the buyers menu selection. These two types are dropprice and dropprice2.

To specify a price altering drop-down box you need to utilize a sub-syntax as the attributes value.

 

[nicepaypal option1="type;name;label;option_value:price;option_value:price;option_value:price]

 

Example

[nicepaypal option1="dropprice;size;Select your t-shirt size;Sm:13.00;Md:15.00;Lg:17.00;Xl:20.00"]

It is important to note that, when using option pricing, you should exclude the use of the item "amount" attribute.

*Note, you may enter as many "option value:price" pairs as you need. For example, if you need to offer 3 different shirt sizes at different prices, you could have a syntaxt that looks like the following.

[nicepaypal option1="dropprice;size;Select your t-shirt size;Sm:13.00;Md:15.00;Lg:17.00"]

 

Alternatively, if you wanted to offer six shirt sizes at different prices, you might have a syntax like the following.

[nicepaypal option1="dropprice;size;Select your t-shirt size;Y:10.00;Sm:13.00;Md:15.00;Lg:17.00;Xl:20.00;Xxl:23.00"]

 

dropprice vs. dropprice2

dropprice and dropprice2 fundamentally function the same in that they use the same tag syntax and both produce a drop-down menu that will alter the product price. The difference  between the dropprice and the dropprice2 option is fairly straight forward. dropprice pre-formats the text that is displayed in the drop down menu list. This is the formating that is followed by dropprice:

 

Option Name+Price

 

dropprice2 is more flexible in that it does not pre-format the option text in the drop-down menu. This added flexibility allows for text display options that will support VAT and GST tax style listings with pricing options. The following tag example shows how this can be accomplished using the tax rate (percentage) option.

[nicepaypal type="buy" name="T-Shirt" tax_rate="10.00" option1="dropprice2;size;Select Size;SM - price including GST - 11.00 AUD:10.00;MD - price including GST - 16.50 AUD:15.00;LG - price including GST - 22.00 AUD:20.00"]

 

The output of the above tag will show a drop down selection  with options like "SM - price including GST - 11.00 AUD" to the buyer. Note that the menu selection label price is inclusive of the tax. However, the actual item price that is sent to PayPal excludes the tax rate. At checkout the pricing will be displayed with the proper sale price and sales tax for the item.

 

Multiple Options Together

You can display multiple options for the same item by simply including multiple attributes.

 

Example

[nicepaypal option1="value" option2="value" option3="value"]

^top

 

return_url

[nicepaypal return_url="url_value"]

You can specify a unique return URL per button, by entering the full URL of your desired return page as the return_url attribute.

 

Example

[nicepaypal return_url="http://www.yourdomain.com/thankyou.html"]

 

For the return URL to work correctly you will need to make a quick change to your PayPal account profile settings. Here is what what to do:

1. Log-in to your PayPal account.

2. go to My Account>>Profile>>Selling Preferences>>Website Payment Preferences>>Auto Return for Website Payments.

3. Select the "On' radio button and enter the the default URL you want the buyer to be returned to, then click submit. The return URL specified in your button tag will override the default URL in set in your PayPal account.

^top

 

cancel_url

[nicepaypal cancel_url="url_value"]

You can specify a unique cancel URL per button, by entering the full URL of your desired cancel page as the cancel_url attribute. Note, please review the documentation for Return URL (above) to ensure your PayPal account profile is set up correctly.

 

Example

[nicepaypal return_url="http://www.yourdomain.com/cancelledpurchase.html"]

^top

 

Hosted PayPal Buttons

Basic support for PayPal hosted buttons is provided by the Nice PayPal Button using the "hosted_button_id" and "encrypted" attributes. To use this feature follow the steps below.

1. Log in to your PayPal account.

2. Go to “Merchant Services”

3. Under Create Button, select the button type ("Add to Cart”, “Buy Now”, etc.).

4. Fill in the button form. Please note that drop down menu options are not currently supported by the Nice PayPal Button plugin for hosted buttons.

5. Click “Step 2”, make sure that the “Save button at PayPal” check box is selected.

6. Click “Create Button”

7. Copy and paste the button code to Notepad or some other text editor.

8. Find the line of code that says “hosted_button_id” and copy the id number that is quoted in the value parameter.

9. Log in to your wordpress site and create a new post.

10. Type the following tag into the post editor. Replace the example hosted_button_id number with the parameter number retrieved in step 8.

 

[nicepaypal type="hosted-cart" hosted_button_id="JK8U665S"]

 

11.Save your post and your done.

 

For other hosted button types use the following syntaxes.

[nicepaypal type="hosted"

[nicepaypal type="hosted-buy"

[nicepaypal type="hosted-pay"

[nicepaypal type="hosted-cart"

[nicepaypal type="hosted-donate"

^top

 

Hosted PayPal View Cart Buttons

To set up a hosted view cart button do the following.

1. After creating a hosted cart button and while you are still on the PayPal copy code page, scroll down a bit and find and click the “Create View Cart Button” link.

2. Except the default PayPal Button setting.

3. Click “Create Button”

4. Copy and paste the button code to Notepad or some other text editor.

5. Find the line of code that says “encrypted” and copy the long string of hash characters that is quoted in the value parameter.

6. Log in to your wordpress site and create a new post.

7. Type the following tag into the post editor. Replace the example hash with the parameter number retrieved in step 5.

 

[nicepaypal type="hosted-cart-view" encrypted="-----BEGIN PxCx9-----vcNAQcEoIIGzjCCBsoCAQExggEwMIIBLAI...............n5ceE3RAW/DYsdw78QH+-----END PxCx9-----"]

 

8.  Save your post and your all done.

^top

 

 

Plugin Options

The Nice PayPal Button Lite plugin allows you to configure the plugin's global settings. Configuration of the plugin is made quick and easy through the use of it's options page. You can find the options page at Admin>>Settings>>Nice PayPal Button Lite. The Global settings that are made available to you are as follows.

 

PayPal Account Email / Merchant Account ID

Enter your valid PayPal account email address. Or, enter your valid Merchant Account ID, which you can find in your PayPal account profile under My Business Info. Payments will be made to the PayPal account associated with this specified email address or merchant id.

^top

 

PayPal Test Mode Email / Test Merchant Account ID

Enter your valid PayPal sandbox test seller email address. Or, enter your valid Merchant Account ID, which you can find in your PayPal sandbox account profile under My Business Info. Test payments will be made to the sandbox account associated with this specified email address. To use this feature you must have a PayPal developer account.

^top

 

PayPal Test Mode

Select on or off to put all PayPal buttons in and out of test mode. When on is specified all transactions are sent to the PayPal sandbox. To use this feature you must have a PayPal developer account.

^top

 

Currency Code

Valid PayPal 3-letter currency codes: Australian Dollars: AUD, Canadian Dollars: CAD, Euros: EUR, Pounds Sterling: GBP, Yen: JPY, U.S. Dollars: USD, New Zealand Dollar: NZD, Swiss Franc: CHF, Hong Kong Dollar: HKD, Singapore Dollar: SGD, Swedish Krona: SEK, Danish Krone: DKK, Polish Zloty: PLN, Norwegian Krone: NOK, Hungarian Forint: HUF, Czech Koruna: CZK, Israeli Shekel: ILS, Mexican Peso: MXN.

^top

 

PayPal Country Code

Enter your 2 digit country code to set the language used on the PayPal payment page. PayPal uses a two-character country code (ISO 3166). Some examples are United States: US, Great Britain: GB, France: FR, Spain: ES, Netherlands: DL, Poland: PL, German: DE. If you don't know your country code, or you can Google PayPal Country Codes.

^top

 

Button Language Code

PayPal uses a 5 character code to designate the language of its buttons. For example, United States English is designated with en_US. Enter the 5 character code for the desired button language. Other code examples are English: en_US, French: fr_FR, Spanish: es_ES, Dutch: nl_NL, Polish: pl_PL, German: de_DE. If you don't know the code for your desired language, log into PayPal use the button creater and search the resulting HTML code for this https://www.paypal.com/en_US/i/btn/btn_buynow_LG.gif. Notice the en_US in the URL, it's the language code for the button.

^top

 

 

Automatic Surcharge Calculator

This optional paramter will allow you to automatically include a percentage based surcharge into all of your item prices. Enter your percentage without the precentage symbol. Example 3% would be entered as 3. Leave blank to exlcude a surcharge.

^top

 

Surcharge Description

Automatically appends item name with a description of the surcharge. Example, if your are selling a WordPress Coffee Mug with a 3% surcharge, you might enter something like "- Price includes a 3% surcharge." The resulting item name will be: WordPress Coffee Mug - Price includes a 3% surcharge.

^top

 

 

Default Button Size

Select the default button size. You can choose between Small and large.

^top

 

New Window Target

Choose how you want the buyer to be sent to PayPal, either in their current browser window or a new browser window.

^top