Developer's Network
Untitled Document

Implementation Guide

Table of Contents

1 Buysafe seal
2 API Overview
3 Cart & Checkout Integration
   3.1 Placement of Elements
   3.2 buySAFE Control
   3.3 OnClick Function for buySAFE Button
   3.4 Rollover Popup Support
4 buySAFE Fee
   4.1 Changes Due to buySAFE Fee
5 Updating the Cart
6 Encoding of results fields
7 Unique MarketplaceItemCode
8 Basket Items with Options
9 Discounts
10 Building ShoppingCartId
11 BuyerInformation for Repeat Customers
12 buySAFE Learn More Link
13 Committing to the Order
14 Order Cancelled
15 Receipt Page Changes
16 Shopper E-mail Changes
17 Authentication Overview

1 BUYSAFE SEAL

buySAFE Seal - This signal indicates a seller is a buySAFE Merchant. The code to include the buySAFE Seal on the site is available through the Merchant Seller Service Center on the buySAFE website; however, partners should assemble the code for merchants within their site administration pages.

Placing the buySAFE Merchant Seal

The pages in the merchant’s store should have the seal placed in a common location (For instance a sidebar or header). There are two pieces of code that need to be added to place the seal and must be present on all pages:

  • Rollover code (this includes the code for WriteBuySafeSeal function)

Production: <script src="https://seal.buysafe.com/private/rollover/rollover.js" type="text/javascript" language="javascript" charset="utf-8"></script>

Sandbox: <script src="https://sb.buysafe.com/private/rollover/rollover.js" type="text/javascript" language="javascript" charset="utf-8"></script>

  • WriteBuySafeSeal Code:

<td align="center" valign="middle"><span id="BuySafeSealSpan" align="center" style="text-align:center;"> <script type="text/javascript">WriteBuySafeSeal( 'BuySafeSealSpan', 'Large', 'HASH=Merchant_Token' );</script> </span></td>

The first parameter is the size (valid values are: Small, Medium, Large) the Merchant_Token is merchant specific and this data will be provided to the integration partner as part of the authentication process. The integration partner will need to store the Merchant_Token for each merchant and substitute the Merchant_Token in the above seal .html template.

NOTE: When the Merchant_Token is inserted into the Seal HTML code, it must be "escaped" to properly conform with the character restrictions for URLs (as defined in RFC 1738). Most programming languages have built-in functions to do this, and are typically called something like "uri escape" or "url encode".

Back to top

2 API OVERVIEW

There are three API calls used for checkout processing:

  • AddUpdateShoppingCart – This call is utilized when a change is made to the shopping cart. This call’s request describes the cart contents, and responds with the visual data (a flash object) required to display the appropriate buySAFE Control to the shopper.
  • SetShoppingCartCheckout – This call is utilized when an order is submitted. This call’s request is identical to AddUpdateShoppingCart, and it simply tells buySAFE that the transaction has been completed. This call should not be made until payment processing has been sucessfully completed.
  • SetShoppingCartCancelOrder – It is issued by the Integration Partner’s Administration Tool when an order has been marked as “Cancelled”. This API essentially “revokes” the bond, and informs the buyer that the bond is revoked.

3 CART & CHECKOUT INTEGRATION

There are three elements that need to be added for cart and checkout pages:

  • buySAFE Control – This signal is used to communicate bonding information to the shopper.
  • buySAFE Fee – The price of the bond.
  • buySAFE Learn More Link

Cart & Checkout Integration Example

Back to top

3.1 Placement of Elements

  • The buySAFE Control should be placed below the subtotal (if present), tax, and shipping and handling rows and directly above the grand total row.
  • The buySAFE Fee should be centered horizontally with the buySAFE Control and appear in the cost column.
  • The placement of the Learn More Link is at the discretion of the Development Partner.

Note: buySAFE signaling must be added to all places where the cart contents are displayed including the Shopping Cart, the Review Order Page (Page which precedes final purchase decision) and the Receipt Page (if the transaction is bonded).
The shopping cart and checkout modifications are summarized in the following tables; each row describes how the buySAFE Control and buySAFE Fee elements fit together for each specific scenario. In these examples, the buySAFE Fee for the Cart is $1.44. The fee is based on the value of contents in the cart.

Buyer's Choice Program

buySAFE Control
buySAFE Fee
Description
  This is how the Control might look when buySAFE Bonding is not selected.
$ 1.44
 When buySAFE Bonding has been selected, the Control changes.
In the infrequent case when bonding is unavailable, a simple hypertext link will be displayed.

Maximum Impact Program

buySAFE Control
buySAFE Fee
Description
Free!
 This Control is used for the Bonded Merchant program.
In the infrequent case when bonding is unavailable, a simple hypertext link will be displayed.

3.2 buySAFE Control

The buySAFE Control is used to communicate bonding information to the shopper. The information displayed is determined by buySAFE based on a number of factors including:

  • buySAFE Program the merchant has chosen (Maximum Impact or Buyer's Choice)
  • Merchant’s status (in good standing, suspended from bonding, over bond limit, etc)
  • Shopper’s location (international or US-based)
  • Specific transactional data (order contains one or more “unbondable” items)

All information required to display the buySAFE Control is included in each API Response, and involves simply inserting the values from the BondingSignal field in the API Response directly into the cart HTML.

The Control is handled by a single flash file (.swf). The BondingSignal field in the API calls will return the code code for the flash file.

The BondingSignal variable from the AddUpdateShoppingCart & SetShoppingCartCheckout API’s indicates what will be displayed on the form.

The buySAFE Control must be added to all shopping cart related pages including the review page (last page before committing to purchase).

If bonding is disabled (isBuysafeEnabled set to FALSE) the button, Learn More link, and buySAFE fee must not be displayed.

Back to top

3.3 OnClick Function for buySAFE Control

Because each Development Partner will have their own unique shopping cart and checkout page, the partner will need to implement the OnClick function for the buySAFE Control. When the Control is clicked, the simplest implementation is to submit the cart FORM. Thus, the button itself must maintain a sense of state so that the FORM processing can properly reflect the buttons state in the WantsBond API field in the AddUpdateShoppingCart call.

In this implementation, the sequence of events would be:

  • Shopper clicks the buySAFE Control
  • OnClick is fired
  • JavaScript performs any state manipulation required and submits the cart to the server
  • Server consumes the FORM data, and send the appropriate fields to AddUpdateShoppingCart (In particular, the new WantsBond state is sent)
  • Server consumes the AddUpdateShoppingCart Response
  • Server constructs the new cart from data in API response and sends it out to the browser
  • The resulting cart now visually reflects the new Bonding state

Note: You MUST name the OnClick Function “buySAFEOnClick”.

3.4 Rollover Popup Support

The buySAFE Control provides additional information to shoppers via rollover popup technology. The information is presented when a user hovers over the Control with their mouse.

Add rollover popup support by

  • Adding the desired “name” attribute to the IMG or A tag to designate which rollover to display.
  • Including a script tag on any webpage that has the buySAFE button. The client-side JavaScript will automatically handle rollover support for the “named” elements.

NOTE: The BuySafeCartButtonHtml has the support for the rollovers built-in. In this case you do not need to add any name attributes but you must still include the rollover script tag.

Back to top

4 BUYSAFE FEE

The buySAFE amount shown in the cost column to the right of the buySAFE control is determined by the BondCostDisplayText field. The fee will shown will either be the dollar amount, “Free!”, or a blank.

Use Case
Displayed in Cost Column
Not Bondable or
Buyer's Choice Merchant with Bonding=Off		 Blank
Bonded Merchant Free!
Buyer's Choice Merchan with Bonding = On $x.xx where xxx = TotalBondCost
Disabled Blank

4.1 Additional buySAFE Fee locations

In addition to changing the shopping cart and checkout pages, the Development Partner must populate the buySAFE Fee throughout their system as appropriate. Typically, this will include:

  • Confirmation e-mail from merchant to shopper
  • Customer order look-up page (if feature is provided)
  • Printable packing slips (if they detail costs)
  • Order total which is sent to payment processors
Back to top

5 UPDATING THE CART

The following cart changes trigger an AddUpdateShoppingCart call:

  • Changes in quantity of any item
  • Adding or deleting items from the cart
  • Toggling of the buySAFE Button
  • Completion of the billing and shipping address information. Note: If billing and shipping is already known for a returning shopper, this information is included in all AddUpdateShoppingCart calls.

buySAFE returns the necessary HTML code to display the buySAFE Control (BondingSignal) and the buySAFE Fee (BondCostDisplayText).

When the call Response is received, the Development Partner must refresh the page contents to show the new results including the updated buySAFE Control and Fees. In the infrequent case where bonding is temporarily unavailable for the merchant (regardless of which program they are in), a hypertext link will be used to display a pop-up window showing an explanation why bonding is unavailable. NOTE: If bonding is disabled when the cart is initiated, the cart will appear without any buySAFE signals.

6 ENCODING OF RESULTS FIELDS

Because merchants may use characters such as & < or > in their titles it is important that all data passed as results in the API must be properly "escaped" to conform with the character restrictions for URLs (as defined in RFC 1738).

7 UNIQUE MARKETPLACEITEMCODE

Partners will use their internal item numbers for the MarketplaceItemCode in the AddUpdateShoppingCart and SetShoppingCartCheckout calls. It is important to note that it must be unique. It is possible to get multiple line items with the same PartNo so before passing MarketplaceItemCode to buySAFE a unique number or letter would have to be added on the end to make it unique.

Back to top

8 BASKET ITEMS WITH OPTIONS

When creating the AddUpdateShoppingCart and SetShoppingCartCheckout call each item in the shopping basket will be added to the Item array. If items can have options, for instance a charge for monogramming or engraving, the item array will contain one entry per product (options will not be separate items regardless of how they appear in the cart), the cost of the product will be the sum total of the item price +/- any prices for the attributes and all options will be communicated through the Attributes field.

9 DISCOUNTS

The cost of a bond is calculated based on the final price of the item.

10 BUILDING SHOPPINGCARTID

The ShoppingCartId sent in the API must be a unique string and may not change for a particular cart. A typical process is to combine a “store prefix” with the browsers Session ID. Usually 8 to 12 characters is enough to make the string unique.
In most cases, the integration partner takes something in their database that already identifies the store (like company name, URL address, or the like) and uses this for the cart prefix.
If a customer continues to shop in a store after checking out a cart it is essential that a new cart ID be created since any AddUpdateShoppingCart calls would result in an error.

11 BUYERINFORMATION FOR REPEAT CUSTOMERS

If the Integration Partner allows its sellers to have buyer registration and the ability to login before the checkout process starts it is important to send this BuyerInformation as soon as it is known and to continue to send that info with all following calls.

Back to top

12 BUYSAFE LEARN MORE LINK

The following example shows how to construct the Learn More Link given the following arguments from the API:
CartDetailsDisplayText = Learn more about buySAFE.

CartDetailsURL= http://www.buysafe.com/Web/Seal/Learnmore.aspx?CartId=samplestore@43243434
<a href=" http://www.buysafe.com/Web/Seal/Bondability.aspx?CartId=samplestore@43243434" target="_buySAFE">Learn more about buySAFE.</a>

13 COMMITTING TO THE ORDER

When the shopper decides to complete the order (all shipping and payment information is assumed to have been collected), and they press the final “buy” button, the SetShoppingCartCheckout API is called. buySAFE will create a “pending Bond” and send a “Your Transaction Is Bonded (YTIB)” E-mail to the shopper.

When the call Response is received, the Development Partner must display the required buySAFE messaging on the Receipt Page.

14 ORDER CANCELLED

The SetShoppingCartCancelOrder call is sent when a merchant marks an item as “cancelled” from within the Partner’s Merchant Administration Tool. This will revoke the bond. Possible conditions which could trigger this include: an order where payment was made with a check that was never received or an item was ordered that cannot be shipped, or if during offline processing the credit card entered is determined to be invalid, etc.

NOTE: This WILL NOT be used for returns or cancelled orders where money has already exchanged hands. Once money has gone from the buyer to the merchant, the bond is in effect. The bond is there to provide refund or cancellation protection in keeping with the merchant’s stated terms of sale. This call may be executed only once per cart.

NOTE: When calling SetShoppingCartCancelOrder you must specify either ShoppingCartId or OrderNumber (or both). They are marked as optional in the API documentation but one of the two is required.

buySAFE will issue an email informing the shopper that the bond is not in effect.

To reactivate a cancelled order a new order will need to be created. The AddUpdateShoppingCart and the SetShoppingCartCheckout API’s can be used with a modified cart ID, for instance appending a –number to the end of it). The contents of the cart can be taken from the cancelled cart. For the reactivated cart the PreviouslyCanceledCartID & PreviouslyCanceledOrderNumber will be set to the value found in the ShoppingCartId & OrderNumber of the cancelled cart.

Back to top

15 RECEIPT PAGE CHANGES

Display the buySAFE Control the way it was displayed in the Cart using the BondingSignal field for the control and the BondingCostDisplayText field for the fee.

If the transaction is not bonded, no buySAFE messaging or graphics will be displayed.

16 SHOPPER E-MAIL CHANGES

If a bond was purchased for a transaction, the merchant’s receipt e-mail sent to shoppers must be updated to include the buySAFE Fee with the following:

  • The same font and alignment as shipping cost or sales tax.
  • Placed after any subtotals (or sales/shipping lines) and directly above the grand total line.
  • Have the following text as its label: “buySAFE Fee”
  • The cost should be aligned with the other costs

Make sure that the “Total” value of the transaction is updated to include the buySAFE Bonding Fee.

Back to top

17 AUTHENTICATION OVERVIEW

The authentication process is a way to exchange critical data between buySAFE and the integration partner in a secure manner (requiring password protected login on both sides). This data is necessary for the partner to issue API calls on the behalf of the seller. The two pieces of data to be communicated are:

  • Store private token – This data is used in the following places:
    • for the AuthenticationTokens in the BuySafeUserCredentials of the soap Header
    • for the UserToken for items in the GetbuySAFEDateTime & SetShoppingCartCheckout API calls.
  • Seal Token – this is used in the .html code that displays the buySAFE Seal.

Both of these pieces of data need to be stored in the integration partner’s system. In most cases, the data will be populated as part of the automatic authentication process. This occurs during the buySAFE registration process if it is initiated from the partner’s administration tool. The integration partner must also provide a user interface within their system for sellers to access this data for manual authentication.

For distribution partners: please download the authentication overview document for additional information.