Untitled Document

TASK 6: SEND CART CHECKOUT INFORMATION TO BUYSAFE

Once an order is placed, you must make a SetShoppingCartCheckout call. This informs buySAFE that the transaction has been completed, at which point we will issue a buySAFE Bond and send a “Your Transaction Is Bonded” email (YTIB) to the customer.

A SetShoppingCartCheckout call can only be made once for each shopping cart. Once this call is made, no further changes can be made to the cart other than to cancel it.

For data integrity reasons, no cart content changes are allowed between the last AddUpdateShoppingCart and the SetShoppingCartCheckout call.

It is essential that a SetShoppingCartCheckout call is sent for EVERY order that is completed, regardless of whether a buySAFE Bond is purchased or not. This enables us to differentiate between shopping carts that never checkout (abandoned carts) and shopping carts that checkout but do not select a buySAFE bond.

STEP 1: CONSTRUCT AND SEND XML REQUEST FOR SETSHOPPINGCARTCHECKOUT CALL

The SetShoppingCartCheckout call is very similar to the AddUpdateShoppingCart call. In fact, it contains all of the same fields, plus a few new ones. Some fields that were available but not required for the AddUpdateShoppingCart call are required for the SetShoppingCartCheckout call.

The following elements are new for SetShoppingCartCheckout call:

The OrderNumber is the unique identifying string that merchant uses to track the order.
If a Bond was purchased, the customer’s email address must be provided in the BuyerInfo.Email field. We need the customer’s email so we can notify them that they have purchased a buySAFE Bond and so that we can correspond with them in case any issues arise. If the customer decided not to purchase a Bond, we do not need their email, but since the field is required by our API, you will need to send us a placeholder such as notbonded@yourstore.com.
The Postal Code and Country Code for Billing Address and Shipping Address are required.
We request that you send the customer’s first and last name so we can use them for any correspondence we have with them, but they are not required.

It is important to note that the items in the SetShoppingCartCheckout call for a cart MUST match the items sent in the most recent AddUpdateShoppingCart call for that cart. If they do not match, our API will respond with an error. This guarantees that the information is current and accurate for the cart being checked out.

SetShoppingCartCheckout request example

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Header>

<Version>VERSION</Version>

</BuySafeWSHeader>

<UserName>USERNAME</UserName>

<Password>PASSWORD</Password>

</MerchantServiceProviderCredentials>

<string>STORE_TOKEN</string>

</AuthenticationTokens>

</BuySafeUserCredentials>

</soap:Header>

<soap:Body>

<ShoppingCartId>ShoppingCartId</ShoppingCartId>

<OrderNumber>OrderNumber</OrderNumber>

<LastName>Buyer</LastName>

<Email>testbuyer@buysafe.com</Email>

<BuyerType>Unknown</BuyerType>

</BillingAddress>

</ShippingAddress>

</BuyerInfo>

</WantsBond>

<Items>

<UserToken>STORE_TOKEN</UserToken>

<Title>checkAPI Test Item </Title>

<MarketplaceItemCode>checkAPI</MarketplaceItemCode>

</FinalPrice>

</PriceInfo>

<ViewItem>http://www.buysafe.com</ViewItem>

</URLInfo>

</ShoppingCartItem>

</Items>

</ShoppingCartCheckoutRQ>

</SetShoppingCartCheckout>

</soap:Body>

</soap:Envelope>

You need to POST your SetShoppingCartCheckout request to: https://sbws.buysafe.com/BuysafeWS/CheckoutAPI.dll. This will change when we move to production (TASK 11).

The SOAPAction is: http://ws.buysafe.com/SetShoppingCartCheckout

The XMLNS is: http://ws.buysafe.com

IF A BOND WAS SELECTED…

If a bond was selected, you should receive a response such as this:

SetShoppingCartCheckout response example (WantsBond=true)

<?xml version="1.0" encoding="utf-8"?>

<MarketplaceItemCode>checkAPI</MarketplaceItemCode>

</ShoppingCartItemBondDetail>

</ShoppingCartItemBondDetails>

<MiniCartLineDisplayText>buySAFE:</MiniCartLineDisplayText>

<CartInstructionsDisplayText>buySAFE...</CartInstructionsDisplayText>

<CartHeaderDisplayText>buySAFE Bond Guarantee</CartHeaderDisplayText>

<CartLineDisplayText>buySAFE Bond Fee: </CartLineDisplayText>

<BondingSignal><span id="BuySafeButtonDiv"></span><script type="text/javascript">WriteBuySafeButton('BuySafeButtonDiv', 'https://sb.buysafe.com/Web/Seal/Button/BuySafeButton_4900.swf', 'BuySafeButton', '#FFFFFF', 'RolloverType=Receipt&FlashName=BuySafeButton&Clickable=False&HASH=TOKEN&DefaultChecked=True&Callback=buySAFEOnClick&NotBondableText=Bonding+not+available%3cbr%3eClick+for+more+details+%c2%bb&LearnMoreUrl=http%3a%2f%2fsb.buysafe.com%2fWeb%2fGeneral%2fCartInformation.aspx%3fCartId%3dShoppingCartId%26PublicToken%3dTOKEN3d&Bondable=True&BondCost=$0.30&TermA=0&Id=ShoppingCartId&TermB=5');</script></BondingSignal>

<CartDetailsDisplayText>Learn more about buySAFE</CartDetailsDisplayText>

<CartDetailsUrl>http://sb.buysafe.com/Web/General...</CartDetailsUrl>

</ShoppingCartCheckoutRS>

This response is similar to the AddUpdateShoppingCart call response, with one important difference: the BondingSignal (a.k.a. buySAFE Button) that is returned is a static flash/image notifying the customer that they have purchased a buySAFE Bond. This “Receipt” BondingSignal is not clickable. The CartLineDisplayText can be used to describe the buySAFE fee if a graphic cannot be displayed.

Once a valid SetShoppingCartCheckout call has been received for the cart, buySAFE will immediately issue a Bond and send a “Your Transaction Is Bonded” email (YTIB) to the customer.

TASK 7 describes how to handle each response element from the SetShoppingCartCheckout call.

IF A BOND WAS NOT SELECTED…

If a Bond was not selected, you will receive a response where IsBuysafeEnabled=false. From that point forward, no buySAFE signaling should be displayed for that cart.

SetShoppingCartCheckout response example (WantsBond=false)

<?xml version="1.0" encoding="utf-8"?>

<BondingSignal><span id="BuySafeButtonDiv"></span><script type="text/javascript">WriteBuySafeButtonInvisible('BuySafeButtonDiv', 'http://seal.buysafe.com/Web/Seal/Button/BuySafeButtonInvisible.swf', 'BuySafeButton', '#FFFFFF', 'FlashName=BuySafeButton&HASH=TOKEN&TermA=1&Id=ed011241434010277&TermB=3');</script></BondingSignal>

<IsBuySafeEnabled>false</IsBuySafeEnabled>

</ShoppingCartCheckoutRS>

<< PREVIOUS TASK || TOC || NEXT TASK >>