How to Use the PayPal BuyNow Component
The BuyNow JSF component that was created by Jayashri
Visvanathan, wraps the PayPal
BuyNow button functionality so it can be easily reused. This button
enables you to sell individual items on a
website that can serve JavaServer Faces pages.
The main advantage of wrapping
the BuyNow button with a JSF component is that
you can populate various component attributes dynamically by binding
them to properties in a managed bean. Specifically, this can save a
lot of time when you have hundreds of items to sell through your
website. The tag library for
the BuyNow component can be accessed using the
declaration:
<%@taglib prefix="ui" uri="http://java.sun.com/blueprints/ui/14"%>
The BuyNow component renders a form
HTML element that
submits information to PayPal about the item
that the buyer wants to order through hidden form fields. For
this
reason, when you are using this
component in a JSP page, it must not be placed in a form
element. All the basic information that you would post to PayPal
when
you want to complete a transaction is supported as properties on the
BuyNow component. If you have additional information you want to
post to PayPal other than what is
supported on BuyNow component's attributes, you can use of postData attribute on the BuyNow
Component. The postData
attribute accepts a ValueBinding
expression that evaluates to a JavaBean of type
"com.sun.j2ee.blueprints.ui.shopping.BuyNowPostData".
This bean supports all the attributes that you would optionally want to
post to PayPal to complete a transaction.
By default the BuyNow component posts to the PayPal Sandbox. The
Sandbox
is a mirror of the real PayPal site where real financial
transactions aren't made. It is
a safe testing environment used to test PayPal
features such as Website Payments. You may want to run in this mode
until your website is operational and ready to be hosted on a public
domain.
By default, button images are loaded
from the PayPal site. You can configure the "image" attribute to
load
an alternate image if you want to override the default behavior.
You must have Internet access
when you are testing your application, whether in the test mode or in
the production mode because both modes initiate a connection to the
PayPal
Payment service.
An example of the JSF BuyNow component's use is as follows:
<ui:buyNow business="donate@animalfoundation.com" id="buyNow1" itemName="Buy Item One"
amount="100.00" quantity="1" type="BuyNow" postData="#{PayPalBean.postData}" target="paypal"/>
JSP
Tag Attributes
The BuyNowComponent supports
the following attributes in addition to the standard
JSF CommandButton's specific attributes. The corresponding PayPal
attribute names are specified in parenthesis.
- business - Email address of your Paypal account (business)
- amount - Price of the item (amount)
- itemName - Name of the item (item_name)
- quantity -
Number of items (quantity)
- imageUrl -
URL of the 150x50-pixel image displayed as your logo in PayPal Page (image_url)
- postBackUrl - URL to
which PayPal posts information about the transaction. (notify_url)
- paymentCancelledUrl - URL to
which
customer's browser is returned if payment is canceled. (cancel_return)
- returnUrl - URL to which customer's browser will be returned
after completing
payment. (return)
- image - Image for the BuyNow button
- alt - Alternate text to serve as content when the element cannot
be rendered
normally.
- postData - Evaluates to a JavaBean of type BuyNowPostData that
encapsulates any
additional attributes that Sellers might want to post to PayPal (see
below).
- target - Name of a frame where the resource retrieved via
this hyperlink
is to be displayed.
- type - A way to indicate whether this is a BuyNow or a Donations
button.
Supported modes, "BuyNow" or "Donation". Not case sensitive (type)
- testMode - If on, information will
be posted to Sandbox. This attribute is set to "on" by default.
BuyNowPostData Bean
Properties
The BuyNowPostData bean supports the following properties. The
corresponding
PayPal attribute names are specified in parenthesis.
- itemNumber - Passthrough variable for you to track purchases or
donations,passed
back to you at payment completion. (item_number)
- undefinedQuantity - Allows buyer to specify the quantity. (undefined_quantity)
- firstOptionFieldName -
First option field name. If omitted, no variable is passed back to you.
(on0)
- secondOptionFieldName - Second option field name. If omitted, no
variable is passed back to
you. (on1)
- continueLabel - Sets the text for the Continue button on the
PayPal Payment Complete
page. (cbt)
- noteFieldLabel - Label above the note field. (cn)
- paymentPageHeaderImage - Sets the image at the top left of the
payment page. Maximum size 750
pixels wide by 90 pixels high (cpp_header_image)
- headerBgColor - Sets the
background color for the header of the payment page. (cpp_headerback_color)
- headerBorderColor - Sets the border color around
the header of the payment page. (cpp_headerborder_color)
- headerPayFlowColor - Sets the background color for the payment
page below the header. (cpp_payflow_color)
- paymentPageBgColor - Sets the background color of your payment
pages. (cs)
- promptPaymentNote- Prompt customer to include a note with
payment. (no_note)
- promptShippingAddress - Prompt customer for shipping address. (no_shipping)
- pageStyle - Sets the Custom Payment Page Style for payment pages
associated with
this button/link. (page_style)
- submissionMethod - Return method GET or POST (rm)
- currencyCode - Defines the currency in which the monetary
variables are denoted (currency_code)
- handlingCost - Handling charges. This is not quantity-specific (handling)
- invoiceNumber - Passthrough variable you can use to identify your
invoice number for
this purchase. (invoice)
- shippingCost - The cost of shipping this item if you have enabled
item-specific
shipping costs. (shipping)
- additionalItemShippingCost - The cost of shipping each additional
item. (shipping2)
- tax - Transaction-based tax override variable. (tax)
Known Limitations
- For Tech Preview, we do not support handling the attributes that
are
posted by PayPal back to the seller once the payment is complete
- Properties to enable Prepopulating PayPal Forms or Address
overriding
is not supported
References
© Sun Microsystems 2006. All of the material in The
Java BluePrints Solutions Catalog is copyright-protected
and may not be published in other works without express
written permission from Sun Microsystems.