Hack 41 PayPal-Enable Your Flash

Add PayPal Buy Now or Subscription functionality to your Flash- powered online store using the WebAssist PayPal eCommerce Snap-ins .

Increasingly, Flash has been putting the sizzle in the online shopping experience by adding cool interactivity and fancy special effects to otherwise bland web pages. Over the last couple years , Macromedia has added several full-fledged software architectures to support Flash-based transactions. Flash forms take advantage of the enhanced interactive capabilities of the vector-based client and allow all manner of special effects, including visual sorting and drag-and-drop shopping options. The latest versions of Flash also provide standard components for commonly used form elements, such as text fields, checkboxes, radio buttons , and lists, which means that you can accept PayPal payments from within Flash elements on your web site.

4.15.1 Snap in the PayPal Connection

So, what does it take to make the Flash connection to PayPal? In truth, the back-end ActionScript required to make the necessary PayPal connection is extremely complex. The good news, however, is that a Flash extension, developed by PayPal and WebAssist, provides the core functionality while leaving a great deal of room for programmatic customization.

Get the extensionknown as the WA PayPal eCommerce Snap-ins for Flash MXfrom http://webassist.com/Products/ProductDetails.asp?PID=24. The extension is free; you just need to register with WebAssist. Install the extension into Flash MX by double-clicking the downloaded file, or into Flash MX 2004 via Macromedia's Extension Manager. If you have Flash open , you'll need to quit and relaunch the program for the snap-in to appear.

Once the extension is installed, you can straightforwardly handle the basics for adding a Buy Now or Subscription button to your page. If the item you're selling has no options or other complications, you don't even have to touch the ActionScript.

Start by building your basic product page. Make sure there is at least one clickable element (such as a button) on the Flash stage, and give it a name in the Property inspector.

Typically, Flash buttons are used for such an interactive event. If you're design-challenged, the installed extension includes a number of Buy Now or Subscription buttons, located in the PayPal Buttons folder of the Common Libraries window. You can drag these to any location on the stage.

Open the Components panel and look in the WA PayPal eCommerce category. Drag either the Buy Now or Subscription object (these are the actual snap-ins) anywhere onto the stage.

Although the snap-in appears as a visual element at design-time, you won't see it when the movie is published. All of its power is behind the scenes.

To complete the simple Flash PayPal configuration, you'll need to establish the details to be sent. While you can set these values in ActionScript, as explained later in this hack, you can also use the snap-in's Component inspector. Select the snap-in and, in the Property inspector, click the Launch Component Inspector button.

In the Parameters tab of the Component Inspector panel, you'll see a custom dialog box for the snap-ins, as shown in Figure 4-13. Each of the snap-in parameter dialogs is a specialized multitabbed affair.

Figure 4-13. Setting the properties of the PayPal extension in Macromedia's Component Inspector

Take a look at the Component Inspector for the Buy Now snap-in, in which the following parameters are separated into three tabs (General, Item Details, and Shipping):

General tab

PayPal Account

The PayPal recipient's email address (required)

Company Logo

The web address (URL) of your logo graphic (such as a .jpg file), which will be incorporated into the PayPal page

Success URL

A fully formed URL to the web page you want your customers to see after a successful PayPal transaction

Cancel URL

The web address of the page to which customers who cancel are sent

Item Details tab

Item Name/Service

The name of the item being sold

Item ID Number

The product SKU or other ID number passed through to you (not seen by the customer)

Price

The base price of the item

Currency

The type of currency to be used (choices are U.S. dollars, Canadian dollars, euros, British pounds and Japanese yen)

Multiple Units Option

A checkbox that controls whether customers can order a quantity of more than one

Shipping tab

Base Shipping

The shipping cost for a single item

Extra Shipping

Shipping charges added, per additional item, if more than one unit is ordered

Handling

The handling charge, over and above the aforementioned shipping charges, applied to the entire order

Shipping Information Option

A checkbox that determines whether PayPal will request the customer's shipping information

Note Option

An option that allows customers to add a note with their PayPal order

The Subscription Component Inspector parameter dialog is similar to the one for the Buy Now snap-in, but it offers special fields for specifying one-time or recurring billing, as well as trial offers.

For items with properties that are completely covered by the options in the Component Inspector panel, no additional ActionScript is required to complete the PayPal order. All you need do is publish the .swf file and put it in an HTML page on the Web; the rest is automatic. But, of course, you want more, don't you?

4.15.2 Hacking the Hack

So, what's underneath the hood of the WebAssist PayPal eCommerce Snap-ins for Flash MX? Quite a bit, as it turns out. There are 31 different methods embedded in the Buy Now snap-in and 38 in the Subscribe snap-in. Of these, about half are used to set values, and the other half are used to pass those values to PayPal. The setting methods are of prime interest to the Flash/PayPal hacker.

Take a look at a typical example that ties additional options (and their related prices) to a PayPal item. Imagine a fictional online T-shirt emporium that offers a fancy-dancy item available in five different colors and four different sizes. There's no difference in price for the various colors available. However, Flash can represent the different colors quite easily, thus adding a nice visual flair to our product page. T-shirt size , on the other hand, goes up with price: $10.99 for small, $13.99 for medium, $15.99 for large, and $18.99 for extra large.

Again, representing this in the .swf is trivial for Flash MX or Flash MX 2004. The values in the drop-down size list are displayed in a dynamic text variable as the current price. But how do you send the correct item cost and order details to PayPal? Short answer: use the set methods. Here's the longer, code-oriented answerjust place this ActionScript code into your project:

 function setPrice( )  {   // Get the price (based on size list)   var newPrice = sizeList.getValue( ); 1.  BN.setAmount(newPrice); 2.  BN.setItemName(sizeList.getSelectedItem( ).label+" "+colorList.getSelectedItem( ). label+" WebAssist.com T-Shirt"); 3.  BN.setItemNumber(String(sizeList.getSelectedIndex( )) + String (colorList.getSelectedIndex( ))); } 

The function setPrice() is called when the page is first loaded and each time any option changes. Both options ( color and size) are selected from drop-down lists, colorList and sizeList , respectively. The first line of the code picks up the price from the sizeList . The user sees the labels in the list (Small, Medium, Large, and X-Large), but the values are set to prices of 10.99 , 13.99 , 15.99 , and 18.99 . The current item price is established as amount to send to PayPal on line 1.

The Buy Now snap-in instance placed on the stage is named BN, and any methods that relate to that instance are named with the BN prefix. Two more functions are used to set the item name (which is what the customer sees on the Payment For line of the PayPal page) and the item number (a SKU number that is sent to the online store owner for order processing) on lines 2 and 3, respectively.

Any value that you can set in the Component Parameter dialog can be set programmatically in ActionScript. Table 4-1 shows all Buy Now methods that set values.

Table 4-1. Buy Now Button methods that set values

Buy Now method	Argument	Description
setAllowNote( " allow " )	Boolean; true or false	Sets whether the buyer can include a note with the payment. If set to false , your customer will not be prompted to include a note.
setAmount( " amount " )	String	Sets the base amount of the item.
setBusinessID( " business " )	String	Specifies the PayPal ID, or email address, where payments will be sent. This email address must be confirmed and linked to your verified Business or Premier account.
setCancelURL( " url " )	String; fully formed URL	Sets the URL of the page viewed when the Cancel button is clicked. This item is optional; if omitted, users will be taken to the PayPal site.
setCurrency( " currency " )	String; valid values are USD , GBP , EUR , CAD , or JPY	Sets the currency to be used for payment. For example, to use the euro instead of the U.S. dollar, change the currency from USD to EUR . Other available currencies include pounds sterling ( GBP ), the Canadian dollar ( CAD ), and Japanese yen ( JPY ).
setExtraShipping( " amount " )	String	Sets the extra shipping cost per item after the first item. If this optional value is omitted, and your Profile-based shipping is enabled, your customer will be charged the amount or percentage defined in your Profile.
setHandling( " amount " )	String	Sets the handling charge. This is not quantity-specific. The same handling will be charged regardless of the number of items purchased.
setItemName( " name " )	String	Specifies the name or description of the item (maximum 127 characters ).
setItemNumber( " itemNumber " )	String	Sets the item number, SKU, or unique key; this is the pass-through variable with which you can track payments. It will not be displayed to your customer but will get passed back to you at the completion of payment (maximum 127 characters).
setLogoURL( " url " )	String; fully formed URL	Sets the URL to your company logo, an image up to 150 by 50 pixels. This is optional; if omitted, your customer will see your business name (if you have a Business account) or email address (if you have a Premier account).
setNoShipping( " bNoShipping " )	Boolean; true or false	Sets whether shipping information is necessary for checkout. If set to true , your customer will not be asked for a shipping address.
setShipping( " amount " )	String	Sets the shipping charge. If shipping is used and shipping_extra is not defined, this flat amount will be charged regardless of the quantity of items purchased. If you are using item-based shipping, make sure the Override checkbox is checked in your Profile.
setReturnURL( " url " )	String; fully formed URL	Sets the URL of the page to which the customer is sent when the order is complete. This item is optional, if omitted, customers will be taken to the PayPal site.
setTarget( " window " )	String; default value is _self	Sets the target window where the payment processing information will be displayed. The constant _self can be used for the current window, _blank will always open a new window, and _parent will replace the parent frameset. You can also specify another frame in your frameset, such as content .
setUpdateableQuantity ( " updateable " )	Boolean; true or false	Sets whether the buyer can change the quantity on the PayPal site. If set to true , the customer will be able to edit the quantity. If this optional value is omitted or set to false , the quantity will default to 1.

The Subscription methods are, for the most part, the same as the methods that set values; all methods listed in Table 4-1, with the exception of setAmount , setExtraShipping , setHandling , setShipping , and setUpdateableQuery , can also be used with an instance of a Subscription snap-in. Table 4-2 lists the additional Subscription set methods available.

Table 4-2. Subscription Button methods that set values

Subscription method	Argument	Description
setBillContinuous( " billContinuously " )	Boolean; true or false	Specifies whether this is a recurring payment. If set to true , the payment will recur unless your customer cancels the subscription before the end of the billing cycle. If omitted, the subscription payment will not recur at the end of the billing cycle.
setBillingAmount( " amount " )	String	Sets the price of the purchase at the standard rate.
setBillingPeriod( " period " )	String	Specifies the length of the billing cycle. The number is modified by the regular billing cycle units, set by setBillingTime("timeUnit") .
setBillingTime( " timeUnit "	String; valid values are D , W , M or Y	Sets the unit of time that the billing period is measured in ( D =days, W =weeks, M =months, Y =years).
setReattempt( " reattempt " )	Boolean; either true or false	Sets whether to reattempt billing if the payment is declined. If set to true and the payment fails, the payment will be reattempted two more times. After the third failure, the subscription will be canceled. If omitted and the payment fails, payment will not be reattempted and the subscription will be immediately canceled .
setStopAfterBilling( " number " )	String	Specifies the number of payments to occur at the regular rate. If omitted, payment will recur at the regular rate until the subscription is cancelled.
setTrialAmount( " amount " )	String	Sets the trial price. For a free trial, use a value of .
getTrialPeriod( " period " )	String	Sets the length of the trial period. This number is modified by the trial period units, set by setTrialTime("timeUnit") .
getTrialTime( " timeUnit " )	String: valid values are D , W , M or Y	Sets the unit of time in which the trial is measured ( D =days, W =weeks, M =months, Y =years).

Combine Flash's interactive flair with the ActionScript methods to put your customers in the driver's seat and still get all the information you need to process your PayPal order correctly.

Joe Lowery