O4W PayPal Integration

Integrating with Paypal, the online payment provider, is extremely easy with O4W. By integrating with Paypal, your website can immediately accept payment (via credit card or check) without the administrative (or capital) requirements of establishing a merchant account. In addition, since Paypal handles the entire payment transaction, any issues relating to payment security are removed from your site.

In order to accept Paypal payments, you must sign up for a "business" account; go to http://www.paypal.com for more information. Note that once your business account is established, you can specify a number of convenient defaults for order processing (including whether your customers must be Paypal customers themselves, or whether the processing should be "Paypal optional"; whether you want shipping costs calculated automatically, or passed in with each transaction; and many others).

Once you have established your Paypal business account, you will be issued a Paypal business ID; you can use either this value, or the email address you specified for your Paypal account, with the O4W Paypal APIs.

Using PayPal “Buy Now”

Using the Paypal "Buy Now" feature, your customer can immediately purchase a single product from your website. Once the customer has selected to "Buy Now" (either via a link or button on your web page), your O4W stored procedure will use the O4WPayPal call to redirect the browser to PayPal's on-line payment site, where the transaction can be completed.

For example, in the CREATE section of your O4W stored procedure, you might have the following code:

BEGIN CASE

   CASE EVENT _EQC "CREATE"

      O4WForm()

      O4WText("Thanks for visiting my site!  Want to buy my product?  Just click here...")

      O4WImageButton("Buy Me!", "https://www.paypal.com/en_US/i/btn/btn_buynow_SM.gif", "BTNBUY")

      O4WQualifyEvent("BTNBUY", "CLICK")

This will create a button using the Paypal "Buy Now" image. You might choose instead to have your own button, or a 'fancier' image button, or a link, generate the event.

Once the "CLICK" event has been generated (by the customer clicking on the button or link), your O4W stored procedure can call the O4WPayPal API to actually process the purchase. For example, in the CLICK section:

   CASE EVENT _EQC "CLICK"

      O4WResponse()

      rslt = O4WPaypal("buy", "page1", "sample@revelation.com", "sample product", "prod101", "", "15.99", "7.8", "2.99")

This will submit a "buy now" request for product "sample product" (internal product ID "prod101"), with an amount of $15.99, shipping $2.99, and a tax rate of 7.8%, for the business account associated with the email "sample@revelation.com". After the purchase has been completed, a "return to merchant" option should be presented to the user; if they click it, O4W will be called with the event "PAYPAL_BUY" and the ctlentid "page1", and your program can then proceed as appropriate. Note that your program should handle the PAYPAL_BUY event with an O4WForm() call and not an O4WResponse() call, as the entire browser page must be rebuilt.

The parameters of the O4WPayPal "Buy Now" call are:

result = O4WPaypal("BUY", returnID, business, itemName, itemNumber, qty, amount, tax, shipping, itemType, extraFieldNames, extraFieldValues, testFlag)

where:

action (required): "BUY" for the "Buy Now" functionality;

returnID (optional): the ctlentid to pass back in to your routine if "return to merchant" has been selected (if null "", then itemNumber is used);

business (required): either your Paypal business id or the email you have associated with Paypal;

itemName (required): the name of the item you are selling;

itemNumber (required): the internal product number you are selling;

qty (optional): the item quantity (or null "" for the default of 1);

amount (required): the dollar amount of the sale (without any leading currency indicator);

tax (optional): the tax RATE (without any trailing "%" indicator);

shipping (optional): the dollar amount of the shipping (without any leading currency indicator)(or null "" if not required);

itemType (optional): the type of item (product, service, subscription, etc., or null "" for the default "product");

extraFieldnames (optional): an @FM delimited list of the names of other Paypal specific fields you wish to provide;

extraFieldValues (optional): an @FM delimited list of the associated values for the other Paypal specific fields you wish to provide;

TestFlag (optional): if set to “1”, instructs O4WPayPal to use PayPal’s “sandbox” URL for testing/debugging purposes

By default, the PayPal window will open in the same browser window your form is currently using; if you wish to have PayPal open in a different window, specify “target” as one of the extraFieldnames, and the name of the browser window you wish to create as the associated value in extraFieldValues.

The return value from the O4WPaypal call ("result") will be null ("") if there are no errors, or a message indicating the cause of the error (for example, "invalid request: no itemName specified").

Using PayPal “Add to Cart”

Using the Paypal "Add To Cart" feature, your customer can add one or more products to the PayPal "shopping cart". Once the customer has selected a product to "Add To Cart" (either via a link or button on your web page), your O4W stored procedure will use the O4WPayPal call to redirect the browser to PayPal's on-line payment site, where the shopping cart can be reviewed. At that point, the customer can choose to return to your site for additional items, or can proceed to "checkout" on the Paypal site so the transaction can be completed.

For example, in the CREATE section of your O4W stored procedure, you might have the following code:

BEGIN CASE

   CASE EVENT _EQC "CREATE"

      O4WForm()

      O4WText("Thanks for visiting my site!  Want to buy some of my products?  Just click here...")

      O4WBreak()

      O4WText("Product #1 - Something special! ")

      O4WImageButton("Add to cart", "https://www.paypal.com/en_US/i/btn/btn_cart_SM.gif", "BTNADD_1")

      O4WQualifyEvent("BTNADD_1", "CLICK")

      O4WBreak()

      O4WText("Product #2 - Even better! ")

      O4WImageButton("Add to cart", "https://www.paypal.com/en_US/i/btn/btn_cart_SM.gif", "BTNADD_2")

      O4WQualifyEvent("BTNADD_2", "CLICK")

      O4WBreak()

      O4WText("Product #3 - The best! ")

      O4WImageButton("Add to cart", "https://www.paypal.com/en_US/i/btn/btn_cart_SM.gif", "BTNADD_3")

      O4WQualifyEvent("BTNADD_3", "CLICK")

      O4WBreak()

This will create several buttons using the Paypal "Add To Cart" image. You might choose instead to have your own buttons, or 'fancier' image buttons, or links, generate the events.

Once the "CLICK" event has been generated (by the customer clicking on a button or link), your O4W stored procedure can call the O4WPayPal API to actually process the purchase. For example, in the CLICK section:

   CASE EVENT _EQC "CLICK"

      O4WResponse()

      whichProduct = field(CTLENTID, "_", 2) ;* determine which button the user clicked

      * A real system would read this information from their database...

      productName = "Product #":whichProduct

      prodID = "prod10":whichProduct

      amount = 10.50 * whichProduct

      rslt = O4WPaypal("add", "page3", "sample@revelation.com", productName, prodID, "", amount, "7.8", "2.99")

This will submit an "Add To Cart" request for whichever product the user selected ("Product #1", "Product #2", or "Product #3"), with the appropriate internal product ID and a calculated sale amount, fixed shipping of $2.99, and a tax rate of 7.8%, for the business account associated with the email "sample@revelation.com". The browser would take the customer to the PayPal site where they could review their shopping cart at this time, make changes to their order, continue shopping, or check out. If the user chooses the "continue shopping" button, O4W will be called with the event "PAYPAL_ADD" and the ctlentid "page3", and your program can then proceed as appropriate. Note that your program should handle the PAYPAL_ADD event with an O4WForm() call and not an O4WResponse() call, as the entire browser page must be rebuilt.

The parameters of the O4WPayPal "Add To Cart" call are:

result = O4WPaypal("ADD", returnID, business, itemName, itemNumber, qty, amount, tax, shipping, itemType, extraFieldNames, extraFieldValues, TestFlag)

where:

action (required): "ADD" for the "Add To Cart" functionality;

returnID (optional): the ctlentid to pass back in to your routine if "continue shopping" has been selected (if null "", then itemNumber is used);