TASK 5: MANAGE THE BUYSAFE BUTTON
The buySAFE Button is an interactive flash/image object that allows customers to select/deselect the buySAFE Bond.
There are different Button styles available. Here is an example of a commonly used style:
BOND SELECTED
BOND NOT SELECTED
The WantsBond Variable
You will need to keep track of whether or not a Bond has been selected for each cart. This will be sent to buySAFE as the WantsBond elements of the AddUpdateShoppingCart and SetShoppingCartCheckout calls.
You will need to keep track of each cart’s WantsBond status in two ways:
- An internal variable named, for example, WantsBond. This must be stored along with all of the other data for the shopping cart. It must be able to store three values: NULL, true or false.
- A hidden form field on the shopping cart page named WantsBondField. This value is passed back to you when the form is submitted, allowing you to update the cart’s internal WantsBond variable. More information about this is below.
When a cart is initialized, its internal WantsBond variable must be set to NULL or an empty string.
When an AddUpdateShoppingCart call is made, the cart’s internal WantsBond variable is used to set the values of WantsBond.value and WantsBond.HasBoolean in the request. There are three cases:
- If the cart’s internal WantsBond variable is NULL or empty string, send:
<WantsBond>
<Value>false</Value>
<HasBoolean>false</HasBoolean>
</WantsBond>
This will only happen for the first API call. This is equivalent to “unknown”, since the customer has yet to make a selection about the buySAFE Bond.
- If the cart’s internal WantsBond variable is true, send:
<WantsBond>
<Value>true</Value>
<HasBoolean>true</HasBoolean>
</WantsBond>
- If the cart’s internal WantsBond variable is false, send:
<WantsBond>
<Value>false</Value>
<HasBoolean>true</HasBoolean>
</WantsBond>
For every API call except for the first call for a new ShoppingCartID, the buySAFE API will return a checked or unchecked Button based on the WantsBond status that is sent. However, for the first call for a new ShoppingCartID, the buySAFE API will return the appropriate Button based on Buyer Preference (see below) and the merchant's default bonding state.
When an AddUpdateShoppingCart response is received, you must use the BondCostDisplayText to set the value of the cart’s internal WantsBond variable.
- If the BondCostDisplayText has a value, you must set the cart’s internal WantsBond variable to true. This means that a Bond is currently selected for the cart.
- If the BondCostDisplayText is NULL or empty string, you must set the cart’s internal WantsBond variable to false. This means that the customer has decided to deselect the buySAFE Bond.
When the shopping cart page is drawn, the hidden form field WantsBondField must inherit the value of cart’s internal WantsBond variable. This allows the cart’s WantsBond state to be known and manipulated from within the shopping cart page.
When the form is submitted, the current value of WantsBondField will be passed back to you. You will then need to use it to set the cart’s internal WantsBond variable. This is necessary if the WantsBondField has changed, which it will when the buySAFE Button is clicked...
The buySAFEOnClick Function
When clicked, the buySAFE Button object will automatically execute the JavaScript “buySAFEOnClick” function. This is a built-in feature of the Button object. You will not need to call this function yourself.
You will, however, need to write the buySAFEOnClick function yourself. It must be named buySAFEOnClick because that is the name that our Button will be executing.
You need to create this function yourself because it must reference the name of your shopping cart form, which will likely be unique to your cart.
We recommend that you implement the buySAFEOnClick function similar to this, where document.cart is the name of your shopping cart form:
function buySAFEOnClick(NewWantsBondValue) {
document.cart.WantsBondField.value = NewWantsBondValue;
document.cart.submit();
}
NewWantsBondValue will be either ‘true’ or ‘false’.
As shown above, all the buySAFEOnClick function needs to do is:
- Set the hidden form field WantsBondField to the new value that is passed (which is determined by the Button, which knows its current state).
- Submit the form.
| NOTE: Keeping track of the carts' WantsBond status is one of the more complicated aspects of the buySAFE integration. Please do not hesitate to contact your Integration Manager if you have any questions! |
Buyer Preference
buySAFE has recently implemented a new feature: buySAFE's Buyer Preference. If this feature is enabled, when buyers make purchases on your site, buySAFE will remember whether or not they decided to purchase a Bond. Then, when those buyers return to your store, the buySAFE Button will be checked or unchecked based on their previous decision.
If this feature is enabled for your store, the buySAFE Seal will write a cookie called "buySAFEUID". You will then simply need to read this cookie and send the cookie's value in the SessionId field of your AddUpdateShoppingCart calls. If the cookie is not present or is empty, you may either pass along the empty value or skip the SessionId node entirely. You will not need any special code to access the cookie - just read it like you would with any other cookie in your system.
If you have any questions about buySAFE's Buyer Preference feature, do not hestitate to contact your Integration Manager.
TEST: IS THE BUYSAFE BOND SELECTED/DESELECTED WHEN THE BUTTON IS CLICKED?
TEST: IS THE BOND STATUS MAINTAINED IF THE CART IS EXITED AND THEN RETURNED TO?
<< PREVIOUS TASK || TOC || NEXT TASK >>