Untitled Document

TASK 3: SEND CART CONTENTS INFORMATION TO BUYSAFE

An AddUpdateShoppingCart call is made every time a shopping cart page is displayed, since the buySAFE Bonding elements that are returned will need to be displayed within the shopping cart pages.

The information sent via the AddUpdateShoppingCart call will contain all of the items currently in the shopping cart and any buyer information, if it is available. Once this is received, buySAFE will create a shopping cart instance in our system and return to you all of the necessary buySAFE Bonding elements that will need to be displayed in the shopping cart.

STEP 1: CONSTRUCT XML REQUEST FOR ADDUPDATESHOPPINGCART CALL

Depending on what language you are programming in, you will build your XML request differently. Please see our sample code section for specific examples.

Using the header you built in TASK 2, here is what your AddUpdateShoppingCart XML request will look like:

AddUpdateShoppingCart request example

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

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

<soap:Header>

<Version>VERSION</Version>

</BuySafeWSHeader>

<UserName>USERNAME</UserName>

<Password>PASSWORD</Password>

</MerchantServiceProviderCredentials>

<string>STORE_TOKEN</string>

</AuthenticationTokens>

</BuySafeUserCredentials>

</soap:Header>

<soap:Body>

</BillingAddress>

</ShippingAddress>

</BuyerInfo>

<ShoppingCartId>TestShoppingCart</ShoppingCartId>

<SessionId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</SessionId>

<Items>

<UserToken>STORE_TOKEN</UserToken>

<Title>checkAPI Test Item</Title>

<MarketplaceItemCode>checkAPI</MarketplaceItemCode>

</FinalPrice>

</PriceInfo>

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

</URLInfo>

</ShoppingCartItem>

</Items>

<HasBoolean>false</HasBoolean>

<Value>false</Value>

</WantsBond>

</ShoppingCartAddUpdateRQ>

</AddUpdateShoppingCart>

</soap:Body>

</soap:Envelope>

See our API Reference for a full description of all XML elements.

Notes on soap:Body elements

The BuyerInfo section is required for AddUpdateShoppingCart call, but only BuyerInfo.BillingAddress.CountryCode and BuyerInfo.ShippingAddress.CountryCode are required. If these CountryCodes are not known, it is acceptable to send US as default. Any other buyer information can be sent if it is available. It is often available if a customer logs into your website before making their purchase.
ShoppingCartId must be unique for each cart. It must also not change throughout the life of a cart. We recommend that you prefix each ShoppingCartId with your buySAFE username.
ClientIP is a required field. This must be the buyer’s IP address.
SessionID represents the buyer's bonding session ID. This element is necessary for the Buyer Preference feature. More information about the Buyer Preference feature can be found in TASK 5.

Notes on ShoppingCartItem elements

For each item in the shopping cart, you must send the following information:

The store token, provided by buySAFE. This must match the AuthenticationToken in the SOAP header.
The title of the item. Be sure that all characters are properly XML-encoded. In particular, &, <, and > will need to be escaped to their proper entities.
The MarketplaceItemCode. This is the unique item identifier that is used within the merchant’s store.
The QuantityPurchased. If two or more identical items exist in the shopping cart, they must be sent as a single item with a multiple quantity. Our API will not accept multiple identical items.
The item’s price. PriceInfo.FinalPrice includes a Value and CurrencyCode. This must be the unit price for a single item. If a multiple quantity exists for an item, the PriceInfo should remain the same. CurrencyCode must be USD, and the Value must represent US Dollars. Taxes, discounts or any other price modifiers should NOT be included in the item price.
The item’s URL. This is sent as the URLInfo.ViewItem.

See TASK 5 for a detailed explanation of the WantsBond variable.

For the first AddUpdateShoppingCart call for any cart, send WantsBond.HasBoolean=false and WantsBond.Value=false. This is equivalent to “unknown”, since the customer has yet to make a selection.

TEST: ECHO XML REQUEST AND VERIFY THAT ALL ELEMENTS ARE BEING CONSTRUCTED PROPERLY

STEP 2: SEND XML REQUEST VIA ADDUPDATESHOPPINGCART CALL

Once the AddUpdateShoppingCart XML request has been constructed, it must be sent to the buySAFE Website Bonding API.

Depending on what language you are programming in, you will send your XML request differently. Please see our sample code section for specific examples.

Since we developing on the buySAFE sandbox environment, you need to POST your AddUpdateShoppingCart 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/AddUpdateShoppingCart

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

You should receive a response such as this:

AddUpdateShoppingCart response example

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

<MiniCartLineDisplayText>buySAFE:</MiniCartLineDisplayText>

<CartInstructionsDisplayText>buySAFE...</CartInstructionsDisplayText>

<CartHeaderDisplayText>buySAFE Bond Guarantee</CartHeaderDisplayText>

<CartLineDisplayText>buySAFE Bond Fee: </CartLineDisplayText>

<CartDetailsDisplayText>Learn more...</CartDetailsDisplayText>

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

<BondingSignal><span id="BuySafeButtonDiv"></span><script type="text/javascript">WriteBuySafeButton('BuySafeButtonDiv', 'https://sb.buysafe.com/Web/Seal/Button/BuySafeButton_4900.swf', 'BuySafeButton', '#FFFFFF', 'RolloverType=Certified&FlashName=BuySafeButton&Clickable=True&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%3dTEST%400.8347676%3a5379%26PublicToken%3dTOKEN&Bondable=True&BondCost=$2.40&TermA=1&Id=TEST%400.8347676%3a5379&TermB=5');</script></BondingSignal>

</ShoppingCartAddUpdateRS>

If you do not receive a valid response, please contact your buySAFE Integration Manager. See TASK 10 for more information about error-handling.

TEST: SEND ADDUPDATESHOPPINGCART CALL AND VERIFY THAT RESPONSE FROM BUYSAFE IS RECEIVED

STEP 3: PARSE XML RESPONSE FROM ADDUPDATESHOPPINGCART

The XML response to the AddUpdateShoppingCart call contains all of the necessary buySAFE Bonding elements that will need to be displayed within your shopping cart. These elements will need to be parsed out of the response.

Depending on what language you are programming in, you will parse the XML request differently. Please see our sample code section for specific examples.

The current implementation of buySAFE Website Bonding utilizes the following response elements from the AddUpdateShoppingCart call:

TotalBondCost
CartDetailsDisplayText
CartDetailsUrl
BondingSignal
BondCostDisplayText
IsBuysafeEnabled

TASK 4 describes how to handle each response element.

TEST: ECHO XML RESPONSE ELEMENTS

NOTES FOR SHOPPING CART PLATFORMS:

It is essential that all ShoppingCartIds are completely unique across your entire platform. We recommend prefixing all ShoppingCartIds with the store name.

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