Developer's Network
Untitled Document

Implementation Guide

Table of Contents

1 buySAFE Trust API – Overview
    1.1 Introduction
    1.2 Flexible and functional
    1.3 How does it work?
    1.4 Types of applications 3rd party can build
2 Getting started
3 Supported Environment
4 WSDL URL Location
5 Hardware requirements
6 Standard data for all messages
7 Third party UI integration Style Guide
8 Implementation description
    8.1 Basic API Calls and output
    8.2 Error Handling
9 Call descriptions
    9.1 VerifyMerchant
        9.1.1 VerifyMerchantRQ: Request details
        9.1.2 Sample XML Request
        9.1.3 VerifyMerchantRS: Response details
        9.1.4 Sample XML Response
    9.2 GetItems
        9.2.1 GetItemsRQ: Request details
        9.2.2 Sample XML Request
        9.2.3 GetItemsRS: Response details
        9.2.4 Sample XML Response
    9.3 GetTrustRating
        9.3.1 GetTrustRatingRQ: Request details
        9.3.2 Sample XML Request
        9.3.3 GetTrustRatingRS: Response details
        9.3.4 Sample XML Response
        9.3.5 WriteTrustSignal Function

1 buySAFE Trust API – Overview

This document is not contractual. We encourage you to continuously check the buySAFE TRUST API documentation regularly or contact your buySAFE TRUST API program manager with any questions.

1.1 INTRODUCTION

Online consumers lack a ubiquitous trust signal that informs them which online merchants are the most reputable. buySAFE provides these ubiquitous trust signals, that allow shoppers to buy with confidence. The buySAFE Trust API enables third-party developers to create innovative solutions that utilize the power of the buySAFE trust signals in their applications. As a member of the buySAFE API developer’s network, your shopping application will be powered by the strongest trust signal available on the web.

In addition to the authentication of merchants or items as Certified or Bonded by buySAFE, the buySAFE Trust API allows partners to access many other buySAFE data points and leverage this information to add value to buyer centric applications and merchant tools.

1.2 FLEXIBLE AND FUNCTIONAL

The buySAFE Trust API provides programmatic access to buySAFE’s proprietary data which evaluates in real time the buySAFE status of a merchant or item for sale, and returns the appropriate signal and data to your application.

A buySAFE certified application CAN:

  • VerifyMerchant - Display the bonding status of merchants
  • GetTrustRating - Display the buySAFE safe shopping rating for a merchant
  • GetItems - Display the bond status of an item

A buySAFE certified application WILL:

  • Reinforce buySAFE positioning as the leader in online trust
  • Display the signals and data accurately
  • Create synergies between buySAFE and the 3rd party proprietary solutions to bring original solutions to users
  • Give proper credit to buySAFE as defined in the buySAFE Trust API UI guidelines

1.3 HOW DOES IT WORK?

The buySAFE Trust API web service supports the SOAP protocol. A 3rd party developer can generate a business object interface from the WSDL document.

For instance, a standard call will request the buySAFE merchant status through the API (VerifyMerchant API call).

  1. The 3rd party application originates the call with one or several merchant URL identifiers.
  2. buySAFE will authenticate origin of the call and will then request data from the buySAFE database.
  3. buySAFE will respond with information to properly display the merchant's bonding status.
  4. Requester’s application will receive answer and will display appropriate signal (buySAFE served).

1.4 TYPES OF APPLICATIONS 3RD PARTY CAN BUILD

By using the buySAFE Trust API, third parties will have access to a variety of data points that can be used to improve various tools:

  • Search utilities
    Calls designed to use and optimize Trust signals in search listings
    • Verification of a domain (Bonded Merchant) or item status (Bond availability and type)
    • Safe shopping rating signals
  • Buyer tools
    Calls designed to increase buyer awareness and buying propensity.
    • Bond validity

2 Getting Started

The following steps describe the sequence of events for a 3rd party developer to apply and use the trust API:

  1. Review this documentation
  2. Request, sign and return the API License Agreement to developer@buysafe.com
  3. Request a sandbox Token from developer@buysafe.com
  4. Build your application
  5. Application review (Performed by support team and you)
  6. Certification by buySAFE integration manager
  7. Request a production token from developer@buysafe.com

3 Supported Environment

Any SOAP-supporting language.

4 WSDL URL Location

Sandbox: http://sbws.buysafe.com/BuysafeWS/TrustAPI.dll?login=<your_id>&password=<your_password>

5 Hardware Requirements

buySAFE does not have any specific hardware requirements at this time, hardware requirements will be the responsibility of the 3rd party.

6 Standard Data for all API calls

  1. User Credentials (username/password)
  2. Version

7 Third Party UI Integration Style Guide

buySAFE signals must be placed in direct relation to the appropriate domain / merchant description. These signals are served by buySAFE, hence, signal placement (handled by the 3rd party) needs to provision for pixel size and overall UI adequacy.

In search (45x15 pixels):

Some UI implementations may be needed for 3rd party toolbars or products which require customized placement and signaling. The buySAFE product and marketing teams will collaborate with you if your application requires specific graphic elements.

Proper credit to buySAFE will be displayed in your application and on your website. When buySAFE signals are displayed, ‘powered by buySAFE’ will be displayed in appropriate sections or pages of your application. Prior written consent from buySAFE is needed to display the buySAFE signals if other seals, labels, or any other 3rd party signals are to be displayed in conjunction with the buySAFE signals.

Signals served by buySAFE can not be resized or altered in any way. If a 3rd party developer needs specific visual and design elements, please contact our developers support team. For further details on UI integration, please refer to the buySAFE Trust API license agreement.

8 Implementation Description

8.1 BASIC API CALLS AND OUTPUT

VerifyMerchant
• Requests bonded merchant verification by buySAFE for an array of merchant domains
• Answer returns TRUE / FALSE (and merchant details)
• Returns the TrustSignal graphic to display on positive results

GetItems
• Requests item verification by buySAFE for a given item.
• Answer returns bond availability (True / False).

GetTrustSignal
• Requests a safe shopping rating for an array of merchant domains
• Answer returns bond availability (True / False).

8.2 ERROR HANDLING

The Item Validation Web Service provides transaction status information through the TransactionStatus object. After calling the ValidateItemStatus method, the TransactionStatus object can be retrieved to check the status of the transaction.

The isSuccessful property of the TransactionStatus object indicates whether the transaction is processed successfully. If there are errors, detailed information can be retrieved from the AdvisoryList property.

Examples:

<TransactionStatus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://ws.buysafe.com">
<TransactionId>53024</TransactionId>
<isSuccessful>false</isSuccessful>
<AdvisoryList>
<AdvisoryInfo>
<isFatal>true</isFatal>
<ErrorCause>Value cannot be null.</ErrorCause>
<ErrorSolution>Contact apisupport@buysafe.com and include ErrorCause and TransactionId along with detail steps on how the error occured</ErrorSolution>
</AdvisoryInfo>
</AdvisoryList>
</TransactionStatus>

<TransactionStatus xmlns="http://ws.buysafe.com">
<TransactionId>12345</TransactionId>
<isSuccessful>true</isSuccessful>
</TransactionStatus>

9 Calls Descriptions

9.1 VERIFYMERCHANT

The objective of this call is for a partner to validate merchant bonding status.

9.1.1 VerifyMerchant request

Request input parameters should identify what element(s) are to be authenticated by buySAFE:
• Marketplace and Merchant User ID
Ex: Marketplace=eBay and UserID=marc123
OR:
• Merchant domain or full URL in which domain is included:
Ex: www.marc1010.com or http://www.marc1010.com/ …/ results

9.1.2 Sample XML request

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

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

         <Version>610</Version>

      </BuySafeWSHeader>

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

            <UserName>your username provided by buySAFE</UserName>

            <Password>your password provided by buySAFE</Password>

         </MerchantServiceProviderCredentials>

   </soap:Header>

   <soap:Body>

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

         <GetVerifyMerchantRQ>

            <Urls>

               <string>the URL of the first merchant to verify</string>

               <string>the URL of the second merchant to verify</string>

            </Urls>

         </GetVerifyMerchantRQ>

      </VerifyMerchant>

   </soap:Body>

</soap:Envelope>


9.1.3 VerifyMerchantRS: Response details

There will be a VerifyMerchant node for each URL sent in the request.

Use the URL returned to match the request to the reponse. This is an echo of the URL that was sent in the request.

The TrustSignal can be used to display buySAFE signalling for valid buySAFE merchants.

9.1.4 Sample XML response

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

<GetVerifyMerchantRS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://ws.buysafe.com">

      <Merchants>

            <VerifyMerchant>

                  <TrustSignal>HTML snippet to display the buySAFE image</TrustSignal>

                  <Url>URL of the merchant</Url>

                  <IsValid>boolean</IsValid>

                  <RegistrationDate>2006-09-25T13:01:30.953</RegistrationDate>

                  <MarketplaceName>the merchant's marketplace</MarketplaceName>

                  <IsCertifiedMerchant>boolean</IsCertifiedMerchant>

                  <Hash>a unique hash code to identify the merchant</Hash>

            </VerifyMerchant>

      </Merchants>

</GetVerifyMerchantRS>

9.2 GETITEMS

9.2.1 GetItems Request

This call is used is for a partner to validate the bond status of a given product / item. This implies that the call made by the requester must include an item identifier and must identify the domain / merchant where the item resides.

Request input parameters should identify what element(s) are to be authenticated by buySAFE:
• Item page URL
Ex: http://www.pcnation.com/web/details.asp?affid=305&item=P47270
Or: http://cgi.ebay.com/3-24-CT-ROUND-DIAMOND-TENNIS-BRACELET-18-K-WHITE-GOLD_W0QQitemZ290007455281QQihZ019QQcategoryZ43348QQrdZ1QQcmdZViewItem

• Item number or identifier (UPC, SKU …) included in the aforementioned URL
Ex: P47270: in http://www.pcnation.com/web/details.asp?affid=305&item=P47270
Or: 290007455281 in:
http://cgi.ebay.com/3-24-CT-ROUND-DIAMOND-TENNIS-BRACELET-18-K-WHITEOLD_W0QQitemZ290007455281QQihZ019QQcategoryZ43348QQrdZ1QQcmdZViewItem
• Marketplace ID: String, identifier of the marketplace on which the item is located.

The request class GetItemsRQ has one property that needs to be filled: ItemList. The ItemList property is an array of Items type. The Items type has the following fields:
• <MarketplaceItemCode>: The unique item code of the marketplace on which the item is displayed
• <ViewItemURL>: URL of the page on which the item is displayed

9.2.2 Sample XML request

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns1="http://ws.buysafe.com">

    < SOAP-ENV:Header >

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

         <Version>600</Version>

      </BuySafeWSHeader>

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

         <UserName>..your username provided by buySAFE</UserName>

         <Password>..your password provided by buySAFE</Password>

      </MerchantServiceProviderCredentials>

   </SOAP-ENV:Header>

   <SOAP-ENV:Body>

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

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

            <ItemReqDetail>

               <GetItemRequestDetail>

                  <MarketplaceItemCode>1234</MarketplaceItemCode>

                  <ViewItemUrl>http://www.ebay.com/viewitem</ViewItemUrl>

               </GetItemRequestDetail>

               <GetItemRequestDetail>

                  <MarketplaceItemCode>2345</MarketplaceItemCode>

                  <ViewItemUrl>http://www.ebay.com/viewitem</ViewItemUrl>

               </GetItemRequestDetail>

            </ItemReqDetail>

         </GetItemsRQ>

      </GetItems>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope 


9.2.3 GetItemsRS: Response details

The response object contains a list of item status values, the list of an array of ItemStatus type.

Field Description Format
IsSealed indicates whether the item is a valid buySAFE bonded item
MarketplaceItemCode The unique item code of the marketplace on which the item is displayed
ItemSignalHTML Returns URL of signal to be displayed for authenticated items URL

9.2.4 Sample XML response

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

      <TransactionStatus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://ws.buysafe.com">

         <TransactionId>53022</TransactionId>

         <isSuccessful>true</isSuccessful>

      </TransactionStatus>

   </soap:Header>

   <soap:Body>

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

         <GetItemsRS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://ws.buysafe.com">

            <RolloverHtml>&lt;SCRIPT src="http://www.buysafe.com/toolbar/rollover-tapi.js" type=text/javascript&gt;&lt;/SCRIPT&gt;</RolloverHtml>

            <ItemImagePath>http://www.buysafe.com/toolbar/images/buySAFE_toolbar_search.gif</ItemImagePath>

               <ItemList>

               <ItemResponse>

                  <isSealed>true</isSealed>

                  <MarketplaceItemCode>1234</MarketplaceItemCode>

                  <HtmlCode>&lt;IMG oncontextmenu="return false" onmouseover="mouseOver('Available', this, '330013463288','undefined','undefined','undefined','undefined' );" onmouseout=mouseOut(); src="http://www.buysafe.com/toolbar/images/buySAFE_toolbar_search.gif"&gt;</HtmlCode>

               </ItemResponse>

               <ItemResponse>

                  <isSealed>false</isSealed>

                  <MarketplaceItemCode>2345</MarketplaceItemCode>

                  <HtmlCode>&lt;IMG oncontextmenu="return false" onmouseover="mouseOver('Available', this, '330013463288','undefined','undefined','undefined','undefined' );" onmouseout=mouseOut(); src="http://www.buysafe.com/toolbar/images/buySAFE_toolbar_search.gif"&gt;</HtmlCode>

               </ItemResponse>

            </ItemList>

         </GetItemsRS>

      </GetItemsResponse>

   </soap:Body>

</soap:Envelope>

9.3 GetTrustSignal

The buySAFE trust signal is a graphic representation of a safe shopping rating. Utilizing the Trust API, a developer can present this signal in any application where a user may want to distinguish shopping sites based on the level of safety. A typical implementation uses the API and a JavaScript helper function contained within the rollover.js file. This file's location is returned in the response.

9.3.1 GetTrustSignal Request

This call is used is for a partner to obtain the buySAFE safe shopping rating for a merchant or merchants.

Request query input parameters:
• ClientIP - The IP of client's browser who will view the rating
• Query - The query used or category selected by the client
• PageNumber - The page number of returned results where the rating will display
• PositionOnPage - The numerical position on the page where the rating will display

Request URL input parameters:
• TargetURLs - The full URL that links to the item

9.3.2 Sample XML request

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns1="http://ws.buysafe.com">

    < SOAP-ENV:Header >

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

         <Version>610</Version>

      </BuySafeWSHeader>

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

         <UserName>..your username provided by buySAFE</UserName>

         <Password>..your password provided by buySAFE</Password>

      </MerchantServiceProviderCredentials>

   </SOAP-ENV:Header>

   <SOAP-ENV:Body>

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

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

            <QueryData>

               <ClientIP>

               <Query>

               <PageNumber>

               <PositionOnPage>

            </QueryData>

            <TargetUrls>

               <string>

               <string>

               <string>... up to 200 URLs

            </TargetUrls>

         </GetTrustRatingRQ>

      </GetTrustRating>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope 

9.3.3 GetTrustSignal Response

Response TrustRating parameters:
• isEcommerce - A boolean value to indicate if this is an actual storefront
• Rating - The numerical safe shopping rating

Response buySAFE parameters:
• isCPA - A boolean value to indicate if this merchant is utilizing the Bonded Shopping Network
• isCertified - A boolean value to indicate if this merchant is utilizing the merchant pays model

• TargetDomain - The domain that has been rated

• TargetUrl - An echo of the URL that was submitted in the request


9.3.4 Sample XML response

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

<GetTrustRatingRS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://ws.buysafe.com">

      <RolloverFileLocation>http://sb.buysafe.com/private/rollover/rollover.js </ RolloverFileLocation>

      <GetTrustRating>

            <Merchant>

                  <TrustRating>

                     <isEcommerce>boolean</isEcommerce>

                     <Rating>numeric</Rating>

                  </TrustRating>

                  <buySAFE>

                     <isCPA>boolean</isCPA>

                     <isCertified>boolean</isCertified>

                  </buySAFE>

                  <TargetDomain>string</TargetDomain>

                  <TargetUrl>string</TargetUrl>

            </Merchant>

      </GetTrustRating>

</GetTrustRatingRS>


9.3.5 WriteTrustSignal function

Returned as part of the GetTrustSignal response is the location of the rollover.js file. This file should be utilized on every page that will display the safe shopping rating. The file contains all the necessary graphics and helper functions to display the image and it's corresponding rollover grapic correctly. Simply call the WriteTrustSeal JavaScript function wherever the image should be displayed. Pass to it the following parameters:

  • ElementName - the name of the span in which the function call is made. By incrementing this value the function can be called multiple times on the same page.
  • Size - Small, Medium or Large
  • TargetFullURL - From GetTrustSignal API response
  • TargetDomainURL - From GetTrustSignal API response
  • AffilateID - Provided by buySAFE when development starts
  • ProgramID - Provided by buySAFE when development starts
  • Query - The search term used to find the item
  • IsEcommerce - From GetTrustSignal API response
  • Rating - From GetTrustSignal API response

The following provides a sample of the JavaScript that may be used to call the WriteTrustSeal function: 

<script src="https://sb.buysafe.com/private/rollover/rollover.js"></script>

<div><span id="span11">

<script type="text/javascript">

            Affiliate=new buySAFEAffiliate();

            Affiliate.ElementName="span11";

            Affiliate.Size="Small";

            Affiliate.TargetFullURL="";

            Affiliate.TargetDomainURL="";

            Affiliate.AffiliateID="";

            Affiliate.ProgramID="";

            Affiliate.Query="";

            Affiliate.SearchResultNumber="";

            Affiliate.IsEcommerce="";

            Affiliate.Rating="";

            Affiliate.WriteTrustSeal();

</script>

</span></div>

 

 

Sample Output

legal notices | buysafe.com | contact us
©Copyright 2006-2007 buySAFE, Inc.