Download Plugin (zip)

Stats

Version

0.4

Wheels Compatibility

1.1.1, 1.1, 1.1 RC 1, 1.1 Beta 2, 1.1 Beta 1

Downloads

269

Last Updated

March 21, 2011

About Plugins

Plugins allow you to extend or modify default Wheels application behavior. To use, you just drop the zip file into your plugins directory and reload your application.

Read Using and Creating Plugins for more information.

paypalButton

Builds and returns a form using the PayPal HTML Variables for the Website Payments Standard

Author

Yannick Morin

Project Home

https://github.com/bizonbytes/paypalButton

Description

paypalButton Plugin

Description

Let you create a paypal button and also validate transaction using Instant Payment Notification (IPN).

Functions available are:


showPaypalButton()

Description

Builds and returns a form using the PayPal HTML Variables for the Website Payments Standard.

Parameters

Parameter Type Required Default Description Type of button that can use this parameter
type string No _xclick

The type of button to display. Those are the options available for you:

  • _cart (for the shopping cart)
  • _xclick (for the Buy Now)
  • _donations (for the Donations)
  • _oe-gift-certificate ( for Gift certificates)
  • _xclick-subscriptions (for Subscriptions)
N/A
cart string No add

For shopping cart purchases; these additional variables specify the kind of shopping cart button or command:

  • add – Add to Cart buttons
  • display – View Cart buttons
_cart (for the shopping cart)
shoppingUrl string No   Enter the URL where recipients can shop and redeem this gift certificate. _oe-gift-certificate ( for Gift certificates)
environment string No testing

What paypal environment you want to use? Choose between :

  • testing (for https://www.sandbox.paypal.com/cgi-bin/webscr)
  • production (for https://www.paypal.com/cgi-bin/webscr)

Note: to use testing you need to create a account under the Sandbox.

All
environnentActive boolean No 0

You can let your cfwheels active environment setting manage witch environment to use.

  • Design, Development, Testing, Maintenance will use the PayPal testing environment (https://www.sandbox.paypal.com/cgi-bin/webscr) url.
  • production will use the PayPal production environment (https://www.paypal.com/cgi-bin/webscr)
All
business string Yes   Your PayPal ID or an email address associated with your PayPal account to receive payments. Email addresses must be confirmed. All
lc string No US

Sets the payer’s language for the billing information/log-in page only. For allowable values, see Countries and Regions Supported by PayPal.

All
amount string See description  

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 at the time of payment.

  • Required for Add to Cart buttons
  • Optional for Buy Now and Donate buttons
  • Not used with Subscribe or Buy Gift Certificate buttons
  • _cart (for the shopping cart)
  • _xclick (for the Buy Now)
  • _donations (for the Donations)
taxRate string No   Transaction-based tax override variable. Set this to a percentage that will be applied to amount multiplied the quantity selected during checkout. This value overrides any tax settings set in your account profile. Allowable values are numbers 0.001 through 100.
  • _cart (for the shopping cart)
  • _xclick (for the Buy Now)
quantity numeric No  

Number of items.

Note: The value for quantity must be a positive integer. Null, zero, or negative numbers are not allowed.

  • _cart (for the shopping cart)
  • _xclick (for the Buy Now)
shipping string No   The cost of shipping this item.
  • _cart (for the shopping cart)
  • _xclick (for the Buy Now)
currency string No USD The currency of the payment. For allowable values, see Currency Codes. All
noNote boolean No 1

Do not prompt payers to include a note with their payments. Allowable values for Subscribe buttons:

  • 1 – hide the text box and the prompt

For Subscribe buttons, always include no_note and set it to 1.

All
itemName string See description.  

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

  • Optional for Buy Now, Donate, Subscribe and Add to Cart buttons
  • Not used with Buy Gift Certificate buttons
  • _xclick (for the Buy Now)
  • _donations (for the Donations)
  • _xclick-subscriptions (for Subscriptions)
itemNumber string No   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.
  • _cart (for the shopping cart)
  • _xclick (for the Buy Now)
  • _donations (for the Donations)
showCreditCard boolean No 1 Display credit card logos under the submit button
  • _xclick (for the Buy Now)
  • _donations (for the Donations)
  • _oe-gift-certificate ( for Gift certificates)
  • _xclick-subscriptions (for Subscriptions)
lang string No en

Language for the submit button (include also the alt tag text). Choose between:

  • en (for english)
  • fr (for french)
  • es (for spanich)
  • de (for german)
  • nl (for dutch)
  • zh (for chinese)
  • ja (for japanese)
  • pt (for portuguese)
All
headerImage string No  

The image at the top left of the checkout page. The image’s maximum size is 750 pixels wide by 90 pixels high. PayPal recommends that you provide an image that is stored only on a secure (https) server.

Note: will only work for paypal business account.

All
return string No The browser is redirected to a PayPal web page. The URL to which the payer’s browser is redirected after completing the payment; for example, a URL on your site that displays a “Thank you for your payment” page. All
notifyUrl string No  

The URL to which PayPal posts information about the transaction, in the form of Instant Payment Notification (IPN) messages.

The first level of testing is to ensure that your IPN listener receives messages and handles them appropriately. Try the IPN simulator

All
cancelReturn string No The browser is redirected to a PayPal web page.

A URL to which the payer’s browser is redirected if payment is cancelled; for example, a URL on your website that displays a “Payment Canceled” page

All
cbt string No  

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 return variable must also be set.
All
custom string No  

Custom value as passed by you, the merchant. These are pass-through variables that are never presented to your customer

Length: 255 characters

All
firstName string No  

First name of payer

Length: 32 characters

All
lastName string No  

Last name of payer

Length: 64 characters

All
a3 string No   Regular subscription price. _xclick-subscriptions (for Subscriptions)
p3 string No   Subscription duration. Specify an integer value in the allowable range for the units of duration that you specify with t3. _xclick-subscriptions (for Subscriptions)
t3 string No  

Regular subscription units of duration. Allowable values:

  • 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
_xclick-subscriptions (for Subscriptions)
buttonImage string No   Use custom button images that match the look of your website. Enter the url for the image. All
sameWindow boolean No 1 Target the click event to open on the same window. If false it PayPal will open in a new window. All
debug boolean No 0 The debug will show you what to do if you miss some of the specific parameter requirements. Since some parameter only applies to some type of button. Try it you will see what I mean it won't hurt. All
onLoadSubmit boolean No 0 Should it submit onLoad or not? All
onLoadSubmitMessage string No You Are Being Automatically Redirected to PayPal Message to appear if you use the onLoadSubmit All

verifyPaypalPayment()

Description

Using Instant Payment Notification (IPN) Method it will verify that the transaction is valid. To activate Instant Payment Notification, you will need to enter the URL (notifyUrl from showPaypalButton()) at which you would like to receive the notification posts from your Profile. You need to use this function inside the action of the notifyUrl.

IPN consists of 2 main steps:

Steps Function
1- Once the customer click on the PayPal Button PayPal POSTs the form variables to a URL (notifyUrl) you specify that runs a program to process the
variables
showPaypalButton ()
2- You validate the notification. verifyPaypalPayment ()

Returns

0, if response from PayPal equal INVALID
1, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Completed" and it meets all your checks (price, itemNumber, currency, receiverEmail)
2, if response from PayPal equal VERIFIED and RECEIVER EMAIL not equal to arguments.receiverEmail
3, if response from PayPal equal VERIFIED and PRICE not equal to arguments.price
4, if response from PayPal equal VERIFIED and ITEM NUMBER not equal to arguments.itemNumber
5, if response from PayPal equal VERIFIED and CURRENCY not equal to arguments.currency
6, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Canceled_Reversal"
7, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Completed"
8, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Denied"
9, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Expired"
10, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Failed"
11, if response from PayPal equal VERIFIED and PAYMENT STATUS return "In-Progress"
12, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Partially_Refunded"
13, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Pending"
14, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Processed"
15, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Refunded"
16, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Reversed"
17, if response from PayPal equal VERIFIED and PAYMENT STATUS return "Voided"

Note that the function can return more then 1 value. Ex. the payment status could be pending and also the price, currency, item number and receiver email could have been modified

Parameters

Parameter Type Required Default Description
environment string No testing

What paypal environment you want to use to post back to PayPal system to validate? Choose between :

  • testing (for https://www.sandbox.paypal.com/cgi-bin/webscr)
  • production (for https://www.paypal.com/cgi-bin/webscr)

Note: to use testing you need to create a account under the Sandbox.

environnentActive boolean No 0

You can let your cfwheels active environment setting manage witch environment to use.

  • Design, Development, Testing, Maintenance will use the PayPal testing environment (https://www.sandbox.paypal.com/cgi-bin/webscr) url.
  • production will use the PayPal production environment (https://www.paypal.com/cgi-bin/webscr)
price string No   Enter the price that you want to compare. If not identical it return 5.
itemNumber string No   Enter the item number that you want to compare. If not identical it return 6.
currency string No USD Enter the currency that you want to compare. If not identical it return 7. For allowable values, see Currency Codes.
receiverEmail string Yes   Primary email address of the payment recipient (that is, the merchant). If the payment is sent to a non-primary email address on your PayPal account, the receiverEmail is still your primary email.

paypalCurrencyToLocale()

Description

Convert the PayPal 3-character ISO-4217 currency codes to a locale for ColdFusion processing. Ex.: Lets say you accept the Australian Dollar currency for payment and when a customer makes a payment then PayPal will send you back the following currency code (AUD) but know you want to output the payment using the coldfusion LSCurrencyFormat function then you will need the proper JDK locale code and that is where this function will convert the PayPal code AUD to the JDK locale code (en_AU) that can be used by coldfusion.

Parameters

Parameter Type Required Default Description
currency string No USD Enter the PayPal 3-character ISO-4217 currency code that you want to convert. For allowable values, see Currency Codes.

Usage/Examples

<!--- view code --->
<cfoutput>
#showPaypalButton(type="_cart", cart="add", business="seller_1292691516_biz@hotmail.com", amount="10",itemName="my item",itemNumber="10",debug="1")#
</cfoutput>

Change Log

Version 0.4—March 21, 2011 Download

  • Added the argument "onLoadSubmit" for the function showPaypalButton() -- To submit the form on page load (useful if you want to send data from a user form to paypal.  Ex. amount for donation.)
  • Wheels compatibility: 1.1 Beta 1, 1.1, 1.1 Beta 2, 1.1 RC 1, 1.1.1.

Version 0.3—December 26, 2010 Download

  • Added the function paypalCurrencyToLocale()
  • Wheels compatibility: 1.1 Beta 1, 1.1, 1.1 Beta 2, 1.1 RC 1, 1.1.1.

Version 0.2—December 23, 2010 Download

2.0.

  • Added the function verifyPaypalPayment ()
  • Added the buttonImage parameter for showPaypalButton ()
  • Wheels compatibility: 1.1 Beta 1, 1.1, 1.1 Beta 2, 1.1 RC 1, 1.1.1.

Version 0.1—December 18, 2010 Download

  • Initial release.
  • Wheels compatibility: 1.1 Beta 1, 1.1, 1.1 Beta 2, 1.1 RC 1, 1.1.1.