buySAFE Developers' Network - Website Bonding API

SUPPLEMENTAL TASK 1: ENABLE MERCHANTS TO APPLY TO BUYSAFE

In most scenarios, before a merchant on your plaftorm can enable buySAFE for their online store, they must apply and be accepted by buySAFE.

In order to apply for buySAFE, merchants must provide the following information:

First Name
Last Name
Are they the primary business owner?
Company Name
Address
Phone Number
Average Gross Monthly Sales
Date they began selling online
Store URL

We will also need the merchant's credit card information. This can be provided during the application process or afterwards during the buySAFE orientation (discussed below). This is required because the merchants will be collecting the buySAFE Bond Fee as part of the total cost of their carts. Every month, buySAFE will bill the merchant for the cost of Bonds sold, minus the merchant's revenue share.

There are three methods that your merchants can use to apply for buySAFE:

Registration API - This API accepts all of the necessary merchant information and, if they qualify, returns their buySAFE credentials.
Pre-Filled Application - You can direct your merchants to the buySAFE application pre-filled with their merchant information. Once they submit the application, we can automatically direct them back to your website with their buySAFE credentials.
Manual Application - Merchants can submit the buySAFE application manually. Once they have obtained their buySAFE credentials, they can then copy and paste them into your Shopping Cart Platform interface.

Once a merchant has been accepted as a buySAFE certified merchant, they will be given a Seal Hash and, for each one of their stores, a Store Token.

Application Option #1: Registration API

The easiest way for merchants to apply to buySAFE is if you implement the buySAFE Registration API. This API accepts all of the necessary merchant information and, if they qualify, returns their buySAFE credentials.

Using the buySAFE Registration API, you can allow merchants to enable buySAFE with only a single-click.

The buySAFE Registration API is made up of three API calls:

AddAccount - This method accepts the merchant's information and returned their Seal Hash and Store Token(s).
AddStore - This method is used to add another store to an existing merchant account. It returns the new store's Store Token.
GetAccount - This method accepts a Seal Hash or search parameters and, if a match is found and you have the correct MSP credentials, returns the merchant's account information.

The buySAFE Registration API uses the same MSP Credentials as the buySAFE Website Bonding API. See TASK 2 for more info.

Here is an example of an AddAccount API call:

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

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

</soap:Header>

<soap:Body>

<LastName>Seller</LastName>

<Email>email@gmail.com</Email>

<CompanyName>Test Seller</CompanyName>

<StreetLine1>1234 Street</StreetLine1>

<CityName>Arlington</CityName>

<Type>Business</Type>

</Address>

<Phone>

<Type>Business</Type>

</Phone>

</DateBeganSelling>

</BusinessInformation>

<UserName>merchant_username</UserName>

<AutoGenerateOnCollision>false</AutoGenerateOnCollision>

</LoginInformation>

<Name>Test Store 1</Name>

<Url>http://www.nowhere1.com</Url>

<CheckOutUrl>.../checkout.asp</CheckOutUrl>

<TermsOfSale>[Terms of Sale]</TermsOfSale>

</StoreInformation>

<Name>Test Store 2</Name>

<Url>http://www.nowhere2.com</Url>

<CheckOutUrl>.../checkout.asp</CheckOutUrl>

<TermsOfSale>[Terms of Sale]</TermsOfSale>

</StoreInformation>

</AddStoreList>

<NameOnCard>Test A Seller</NameOnCard>

</ExpirationDate>

</CreditCard>

</PaymentInformation>

</AddAccountRQ>

</AddAccount>

</soap:Body>

</soap:Envelope>

Here is a successful AddAccount response:

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

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

</soap:Header>

<soap:Body>

<Status>Active</Status>

<LastName>Seller</LastName>

<Email>email@gmail.com</Email>

<CompanyName>Test Seller</CompanyName>

<UserName>buysafe_username</UserName>

</AccountResponse>

<Status>Active</Status>

<UserToken>STORE_TOKEN_1</UserToken>

<Name>Test Store 1</Name>

<Url>http://www.nowhere1.com</Url>

</StoreResponse>

<Status>Active</Status>

<UserToken>STORE_TOKEN_2</UserToken>

<Name>Test Store 2</Name>

<Url>http://www.nowhere2.com</Url>

</StoreResponse>

</StoreResponseList>

</AddAccountRS>

</AddAccountResponse>

</soap:Body>

</soap:Envelope>

A merchant's buySAFE Username is used to login to their buySAFE Service Center which provides them information about their account and transactions. buySAFE will create a unique login for each merchant. The LoginInformation.UserName element of the AddAccount request will be used if it is valid. If not, we will attempt to use the Email address provided in BusinessInformation. If this is also not a unique new username, then the AutoGenerateOnCollision element will control the next step. If it is true, we will guarantee a unique username by appending numbers to the end of the UserName provided. If it is false, we will return an error - in which case you may prompt the user for a new username to try.

If the merchant is approved by buySAFE, please display their buySAFE Username, Seal Hash and Store Token(s) and notify them that they will be receiving an email from buySAFE soon. You must also be sure to store the SEAL HASH and STORE TOKEN that are returned by the Registration API.

If the merchant is not approved by buySAFE, please display a message indicating that their buySAFE Application has been declined and that they should contact buySAFE Customer Support at customersupport@buysafe.com.

NOTE #1: If you do not have all of the necessary merchant information for the Registration API, you can still utilize it. To do so, we recommend that you create an interface that allows your merchants to enter in the missing information. Please note which fields are required and which fields are optional.

NOTE #2: If you plan to pass Payment Information using the Registration API, you MUST gain explicit permission from the merchant. Thank you.

For full technical specifications of buySAFE's Registration API, please contact your Integration Manager.

Application Option #2: Pre-Filled Application

If you choose not to implement the buySAFE Registration API, you can direct your merchants to the buySAFE application pre-filled with their merchant information. Once they submit the application, we can automatically direct them back to your website and pass back their buySAFE credentials as a query string within the URL.

The URL for the buySAFE Application page is: https://www.buysafe.com/web/Registration/Seller/Quick/PersonalInformation.aspx

In order to pre-fill the buySAFE Application, you can pass the following data fields as a query string in the URL:

Field	Description	Type
pfHandlerUrl	This is the webpage that you want your merchants to be returned to once they complete the application. If they have been accepted, we will include their buySAFE credentials as a query string on the end of this URL.	char(1000)
pfReturnPassCode	This is a password created by MSP. It will be returned, for validation purposes, as part of the query string of the Handler URL.	char(256)
pfInvitationCode	Promotional code for sign-up discounts. Contact buySAFE for details.	char(50)
pfFirstName	First Name	char(25)
pfMiddleInitial	Middle Initial	char(1)
pfLastName	Last Name	char(25)
pfNameSuffix	Suffix used with name (Jr, Sr, II, III, etc)	char(4)
pfCompanyName	Name of company/business	char(256)
pfWCountryCode	CountryCode as per ISO 3166 list	char(2)
pfAddressW1	Address line 1	char(60)
pfAddressW2	Address line 2	char(60)
pfWCity	City where merchant's business is based	char(30)
pfWState	2 letter code for US states	char(2)
pfWZip	Zip Code	integar
pfPhoneWFull	Merchant's phone number	char(25)
pfEmail	Merchant's email address	char(50)
pfStoreName	The merchant's store name	char(100)
pfStoreURL	The URL of the merchant's primary online store	char(100)
pfMspId	This is the MSP ID value for the Shopping Cart Platform. It will be provided by buySAFE.	integar

Keep it mind that none of these fields are required. You can pass as many or as little as you'd like. Any fields that are not pre-filled will need to be entered manually by the merchant.

Here is an example of a pre-filled application URL:

https://www.buysafe.com/web/Registration/Seller/Quick/PersonalInformation.aspx?pfHandlerUrl=http://www.testmsp.com/buySAFEhandler.aspx&pfReturnPassCode=passcode&pfFirstName=Test&pfMiddleInitial=P&pfLastName=Seller&pfNameSuffix=Jr&pfCompanyName=eStore&pfWCountryCode=US&pfAddressW1=123 Test St&pfAddressW2=Apt 100&pfWCity=Testville&pfWState=VA&pfWZip=11111&pfPhoneWFull=5555555555&&pfEmail=testseller@buysafe.com&pfStoreName=Test Store&pfStoreURL=www.teststore.com&pfMspId=121

And here is an example of a passback URL with the buySAFE Credentials passed as a query string:

http://www.testmsp.com/buySAFEhandler.aspx?StoreData=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&SealData=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PassCode=passcode

If you receive the merchant's credentials via the passback URL, please display their buySAFE Username (if you know it), Seal Hash and Store Token(s) and notify them that they will be receiving an email from buySAFE soon. You must also be sure to store their SEAL HASH and STORE TOKEN.

Application Option #3: Manual Application

If no other methods are implemented, merchants can simply apply to buySAFE manually. You can provide them with the link and instruct them to copy and paste their buySAFE credentials once they have obtained them.

The URL for the buySAFE Application is: https://www.buysafe.com/web/Registration/Seller/Quick/PersonalInformation.aspx

Button to Test buySAFE Credentials

It is recommended that you implement a TEST BUYSAFE CREDENTIALS button. This button will make a GetBuysafeDateTime call using the merchant's credentials and display whether the credentials are valid based on the success or failure of the call. See TASK 2 for more info on the GetBuysafeDateTime call.

buySAFE Orientation

When a new merchant is approved by a buySAFE, they will receive a phone call for their buySAFE orientation. During this orientation a member of our Customer Support team will explain:

What the buySAFE Website Bonding product is and how it will help increase sales on their online store.
How buySAFE will be integrated into their shopping cart.
What a buySAFE Bond is and how Bond Fees are collected.
The dispute resolution process between customers, merchants and buySAFE.
A/B Testing.
The tools available through the buySAFE Merchant Service Center.

If a merchant has not yet provided their credit card information, it will be obtained during the buySAFE Orientation.

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