Getting Started with the Nice PayPal Button Plugin

1. If you don't already have one, sign up for a business PayPal account.

2. Install the plugin using Joomla's Extension Manager.

3. Go to Extensions>>Plugin Manager and click into the plugin “System – Nice PayPal Button.”

4. Enable the plugin.

5. Add your PayPal account email to the parameters on the right.

6. Optionally add your sandbox sellers account email if you plan to do testing.

7. Optionally set the test mode to on or off - the default is off.

8. Optionally enter your PayPal supported 3 letter currency code – default is USD.

9. Optionally, 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, Poland: PL, German: DE. If you don't know your country code, or you can Google PayPal Country Codes.

10. Optionally, set your button language code. PayPal uses a 5 character code to designate language it's 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 Great Britain English: en_GB, French: fr_FR, Spanish: es_ES, Polish: pl_PL, German: de_DE. If you don't know the code for your desired language, log into PayPal use the button creator 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.

11. Save your changes.

12. Important - (ignore this step if you are using Nice PayPal Button version 2.0 or greater) Email Cloaking is a default feature of Joomla. Unless you have specifically disabled it, it is enabled on your site. If this is the case then, in the Plugin Manager, you will need to change the order of the Nice PayPal Button plugin so that it appears below the Email Cloaking plugin in the plugin list. Otherwise, the PayPal buttons that the Nice PayPal plugin creates won't work properly.

13. Add the tag code {nicepaypal:button type|price|item name} to your article (or custom module, etc.) where you want the PayPal button to show up.

Place the Nice PayPal Button tag in your content.

A PayPal button replaces the Nice PayPal button tag.

 

Basic Tag Usage

Usage is simple. Create a new article and add your desired content to it. Wherever you want a PayPal button to appear include this tag {nicepaypal:button type|price|item name}.

Tag Syntax {nicepaypal:button type|amount|item name}

Examples

For a PayPal Buy Now button use this syntax {nicepaypal:buy|5.00|Fluffy Bunny}

For a PayPal Pay Now button use this syntax {nicepaypal:pay|5.00|Fluffy Bunny}

For a PayPal Donation button use this syntax {nicepaypal:donate|0.00|Feed the Children}

Notice that the purchase amount is set to 0, if you set it to 0.00 or leave it blank, e.g. {nicepaypal:donate||Feed the Children}, then the payer will have the option to specify their own donation amount during the PayPal checkout process.

For a PayPal Cart button use this syntax {nicepaypal:cart|5.00|Fluffy Bunny}

Items will be added to the PayPal Cart system as the payer continues to shop, until they checkout. This creates a convenient method for the payer to purchase multiple items from your site and a great way for you to maximize sales.

Extended Tag Usage

This plugin has a number of extended options that make it very flexible and convenient for most merchant's needs.

Extended Tag Syntax {nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity}

Full Extended Usage Example

{nicepaypal:cart|9.95|Delicious Coffee Beans – 1lbs.|sku-1234|4.50|1.25|.73}

When using the additional options you may choose to leave any additional item out by simply omitting the information between the pipes “|” that you wish to leave out, e.g. “item number|||tax”. The example below illustrates an item to be sold utilizing PayPal's cart system with no item number or alternative shipping amount for additional quantities of the same item.

Partial Extended Usage Example

{nicepaypal:cart|9.95|Delicious Coffee Beans – 1lbs.||4.50||.73}

The tag above defines a button that is set to buy one pound of coffee for $9.95 with a shipping charge of $4.50 and a tax of $0.73. Note the blank parameters, the missing information between the pipes “||” omits the option from the button.

Tag Parameter Definitions

Button type

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2}

Select between 6 different button operational types; the PayPal Buy Now button, the PayPal Pay Now button, the PayPal Donation button, the PayPal Cart & View buttons, the PayPal Cart button and the PayPal View Cart button. If omitted the button sill default to a “Buy Now” button.

Three of the button types are variations for the cart type, "cart". "cart_noview" and "cart_view". The button type "cart" will render a Add to Cart & View Cart buttons together. The "cart_noview" type will only render the Add to Cat button. The "cart_view" will only render the View Cart button.

Valid entries are “buy”, "pay", “donate”, “cart”, "cart_noview", or "cart_view"

Custom Button Graphics

{nicepaypal:button type;custom graphic URL|amount|item name....

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

Example

Donate with stabdard PayPal button art - {nicepaypal:donate|10.00|Feed the Children}

Donate with custom button art - {nicepaypal:donate;http:/www.domain.com/images/customdonatebutton.jpg|10.00|Feed the Children}

The second example will result in something like this:

*Please note that custom graphics can be used on any button type except the "cart" type. This is because "cart" renders a combination of two buttons, the Add to Cart and View Cart buttons. Also, here is a partial list of available  PayPal provided button graphics.

Amount

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2}

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

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

Item name

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2}

Description of item. If omitted, payers enter their own name at the time of payment.

Item number

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2}

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.

Shipping

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2}

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 use of the shipping variable is valid only for Buy 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.

Shipping2

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2}

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

Tax

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2}

Transaction-based tax override variable. Set this to a flat tax amount to apply to the transaction 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.

To use your PayPal account tax settings simply leave the tax field blank by using a double pipe "||".

Example

{nicepaypal:cart|$9.95|Fitness DVD|sku 1234|2.50|.50||1}

Item Quantity

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2}

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.

Weight

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2}

Weight of items. 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 leave the shipping and shipping2 fields blank by using a double pipe "||". After which you can optionally specify a item weight by entering a numerical (float) weight value, e.g. 1.5.

Example

{nicepaypal:cart|29.95|Fitness DVD|sku 54321|||2.17|1|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:cart|29.95|Fitness DVD|sku 54321|||2.17|1|1.5kgs}

Option1

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2}

Option 1 has 2 possible configurations, a text entry options field or a drop-down options box.

To specify a text entry options field you need to utilize a sub-syntax as a parameter, |option type;option label;option message;max length of text|

Example

{nicepaypal:cart|17.95|Joomla T-Shirt||||1.30|1|.3|field;size;Enter your size;60}

To specify a drop-down options box you need to utilize a sub-syntax as a parameter, |option type;option label;option message;option value;option value;option value|

Example

{nicepaypal:cart|17.95|Joomla T-Shirt||||1.30|1|.3|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 have a syntaxt that looks like the following.

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

|drop;color;Select t-shirt color;Red;Blue;White;Black;Green;Yellow}

Option2

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2}

Option2 supports the same two option types as the Option1 paramter, using the same syntax. This makes it possible to have two drop-down boxes, two text entry fields, or a combination of the two.

An important difference is that Option2 supports a third option type, a price specifying drop-down box. For example if you offered several shirt sizes and wanted to charge a different price for each size you would use Option2 with a price specifying drop-down box.

To specify a price specifying drop-down box you need to utilize a sub-syntax as a parameter, |option type;option label;option message;option value:price;option value:price;option value:price|

Example

{nicepaypal:cart||Joomla T-Shirt||||1.30|1|.3||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 this third option, you should leave the item "amount" parameter blank by using a double pipe "||", {nicepaypal:cart||Joomla T-Shirt

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

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

|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}

Option1 & Option2 Together

A combined usage of Option1 and Option2 for the same button might look something like the following example.

{nicepaypal:cart||Joomla T-Shirt||||1.30|1|.3|drop;color;Select t-shirt color;Red;Blue;White;Black|dropprice;size;Select your t-shirt size;Sm:13.00;Md:15.00;Lg:17.00;Xl:20.00}

The above tag would result in creating the button below.

Another option might be something like the following.

{nicepaypal:cart||Joomla T-Shirt||||1.30|1|.3|field;size;Enter your size;60|dropprice;size;Select your t-shirt size;Sm:13.00;Md:15.00;Lg:17.00;Xl:20.00}

The above tag would result in creating the button below.

This example of course is a bit silly, since we are asking the buyer to enter their size twice. But, you get the technical concept.

Additional Product Options

You may specify additional options in the option2 field by seperating them with a double semi-colon ";;". Simply define the new options with the same syntax used for option1 and option2. You may specify a total of 9 options, this is PayPal's limit. The nine options include option1.

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2;;option3;;option4} 

Example

{nicepaypal:buy||Joomla T-Shirt||||1.30||.3|field;design-num;Enter the design number;60|field;shirt-type;Enter the shirt type;60;;drop;color;Select t-shirt color;Red;Blue;White;Black;;dropprice;size;Select your t-shirt size;Sm:13.00;Md:15.00;Lg:17.00;Xl:20.00}

The above tag would result in a button that looks something like the following.

Return URL

{nicepaypal:button type|amount|item name|item number|shipping|shipping2|tax|item quantity|weight|option1|option2|return URL}

You can specify a unique return URL per button, by entering the full URL of your desired return page in the return URL field.

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.