Shortcode Attribute Definitions
- type
- custom_button
- amount
- name
- sku
- shipping
- shipping2
- handling
- surcharge
- surcharge_description
- tax
- tax_rate
- weight
- quantity
- button_language
- country_code
- currency_code
- option1 - option9
- return_url
- cancel_url
- PayPal Hosted Buttons
- PayPal Account Email / Merchant Account ID
- PayPal Test Mode Email / Test Merchant Account ID
- PayPal Test Mode
- Currency Code
- PayPal Country Code
- Button Language Code
- Automatic Surcharge Calculator
- Surcharge Description
- Default Button Size
- New Window Target
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"]
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"]
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"]
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"]
name
[nicepaypal name="Item Name"]
The name of the item being sold. If omitted, payers enter their own name at the time of payment.
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"]
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.
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.
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.
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.
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.
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.
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.
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.
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"]
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"]
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"]
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"]
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.
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"]
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.
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"]
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"
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.
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.
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.
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.
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.
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.
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.
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.
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.
Default Button Size
Select the default button size. You can choose between Small and large.
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.