Untitled Document

TASK 2: UNDERSTAND THE BUYSAFE API

The largest part of the buySAFE implementation is the integration of buySAFE Bonding into your website’s shopping cart and checkout process. This is achieved through the three API calls that make up the buySAFE Website Bonding API.

buySAFE Bonding elements are returned when shopping cart information (including item descriptions, prices, quantities, etc) is sent to the buySAFE Website Bonding API. These Bonding elements include the “buySAFE Button”, an interactive flash/image object that allows customers to select/deselect the buySAFE Bond:

Other response elements include:

The cost of the bond, as a numeral.
The cost of the bond, as a string with a $. This can also be returned as ‘Free!’
The text for a “Learn More About buySAFE” link.
The URL for a “Learn More About buySAFE” link.

These elements must be incorporated into the shopping cart as explained in TASK 4.

The three API calls of the buySAFE Website Bonding API are:

AddUpdateShoppingCart – This call’s request describes all of the items currently in a shopping cart. This call’s response contains all of the necessary buySAFE Bonding elements that need to be displayed within the shopping cart (described above). This call must be made whenever anything changes in the cart. Task 3 explains the AddUpdateShoppingCart call in detail.

SetShoppingCartCheckout – This call is made when a shopping cart is checked out and completed. This call’s request must contain the final items in the shopping cart, along with some information about the buyer. This call tells buySAFE that the transaction has been completed, at which point, if the customer has chosen to purchase a Bond, we will issue the Bond and send the buyer a “Your Transaction Is Bonded” email (YTIB) to the customer. In most instances, this call should not be made until payment processing has been successfully completed. Once this call is made, no further changes can be made to the cart other than to cancel it. Task 6 explains the SetShoppingCartCheckout call in detail.

SetShoppingCartCancelOrder – This call is issued by the website’s Administration Tool when an order or bond needs to be canceled. This API tells buySAFE to cancel the buySAFE Bond and inform the buyer that the bond is revoked. Task 8 explains the SetShoppingCartCancelOrder call in detail.

See our Illustrated API Demo for an example of the interaction between the user's actions and the various buySAFE API calls.

Technical Information

For sandbox testing, POST the XML to: https://sbws.buysafe.com/BuysafeWS/CheckoutAPI.dll.
For production, POST the XML to: https://api.buysafe.com/BuysafeWS/CheckoutAPI.dll.
SOAPAction: http://ws.buysafe.com/method_name (This does NOT change when moving to production.)
xmlns: http://ws.buysafe.com (This does NOT change when moving to production.)

STEP 1: BUILD BUYSAFE API SOAP HEADER

All of the buySAFE Website Bonding API calls use a common SOAP header.

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

Your version, username, password and store token will all be provided to you by buySAFE.

Here is what your SOAP header will look like:

<Version>VERSION</Version>

</BuySafeWSHeader>

<UserName>USERNAME</UserName>

<Password>PASSWORD</Password>

</MerchantServiceProviderCredentials>

<string>STORE_TOKEN</string>

</AuthenticationTokens>

</BuySafeUserCredentials>

STEP 2: MAKE GETBUYSAFEDATETIME CALL

We recommend that you test our buySAFE Website Bonding API with the GetBuysafeDateTime call, our simplest API call.

Using the SOAP header that you’ve built, simply add the following line as the SOAP body:

Here is what your full GetBuysafeDateTime XML request will look like:

<?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>

</soap:Body>

</soap:Envelope>

Since we developing on the buySAFE sandbox environment, you need to POST your GetbuySAFEDateTime request to: https://sbws.buysafe.com/BuysafeWS/CheckoutAPI.dll.

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

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

You should receive a response such as this:

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

<GetbuySAFEDateTimeRS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="http://ws.buysafe.com">

</GetbuySAFEDateTimeRS>

If you received a valid response, congratulations! You have made your first successful call to the buySAFE Website Bonding API.

If you need assistance, please contact your buySAFE Integration Manager.

API Transaction Log Reader and Cart Viewer

The buySAFE API Transaction Log Reader is a tool that allows you to see the API calls that you are sending to our Sandbox environment as well as the responses that we are sending back.

The login credentials for the API Transaction Log Reader are your Sandbox Merchant Service Provider username and password, which will be provided to you by buySAFE.

The interface is fairly simple. One feature that may need explanation is the "Request free-text Search". This feature allows you to search for API requests that contain whatever words/phrases you type in the search field. This is useful for finding a particular ShoppingCartId or item, for example. Let us know if you have any questions.

Once you have logged into the API Transaction Reader, you will see a link to our Cart Viewer. This tool shows you the status of every cart that you have submitted to our system.

We hope these tools will prove to be useful during your development!

NOTES FOR SHOPPING CART PLATFORMS:

Your same MerchantServiceProvider credentials are used for every API call that is made for any of your merchants.

Each store will have its own unique Store Token. If a merchant has multiple stores, they will have multiple Store Tokens.

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