Page tree
Skip to end of metadata
Go to start of metadata

Introduction


DOTS BIN Validation is an XML web service that provides information about charge cards. By using the first six digits of the card number (aka BIN or Bank Identification Number), DOTS BIN Validation provides information about the charge card itself as well as the bank that issued the card. 

With BIN validation, users can verify bank and charge card information to protect against fraud and superfluous charge-backs. This information can be used to improve online applications or as supplemental information for existing databases.

Integration

Integration of DOTS BIN Validation into user applications is generally a straightforward process. For common programming platforms, such as ASP, ASP.NET, ColdFusion, PHP, etc., Service Objects will likely have sample code available online:
https://www.serviceobjects.com/developers/sample-code/bin-validation

If the code you seek is not available online, you can ask Service Objects to build a custom example for you. Email support@serviceobjects.com for more details.

Web Service Structure

Web services provide a standard interface to encapsulate tricky business logic. They allow simple integration of applications via the web. Service Objects has followed web services best practices and come up with some of its own standards to ensure that its web services are as easy to integrate, and as accessible as possible.

The host path, or physical location of the web service is here:
https://trial.serviceobjects.com/bv/

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the "Service Definition" link on the web service page.):
http://trial.serviceobjects.com/BV/soap.svc?wsdl


Service XML Request Help Page

https://trial.serviceobjects.com/bv/web.svc/xml/help

Service JSON Request Help Page

https://trial.serviceobjects.com/bv/web.svc/json/help

Important Note!
SOAP is done via POST, only with special XML markup in the post-body.

The WSDL is an XML document that defines the interaction web service, meaning its inputs, outputs, operations, and the like. Most likely, you will have another tool read this WSDL and make the operations available to you in your application via some type of proxy class. Whenever your utilities or IDE asks for a WSDL path, you can provide this one. 

Code Snippets




Bin Validation C# Code Snippet
//Add a service to your application https://trial.serviceobjects.com/bv/soap.svc?wsdl
DOTSBinValidation DOTSBinValidation = new DOTSBinValidation();
BinValidationResult response = DOTSBinValidation.ValidateBIN(BinNumber.Text, LicenseKey.Text);
		
if (response.Error != null)
{
	//Process Error
}
else
{
	//Process Response		
}


Bin Validation Java Code Snippet
BinValidationResult binValidationResult;
DOTSBinValidationLocator locator = new DOTSBinValidationLocator();
DOTSBinValidationSoap soapRequest = locator.getDOTSBinValidationSoap();
binValidationResult = soapRequest.validateBIN(binNumber,key);
Error error = binValidationResult.getError();
BinValidationInfo binInfo = binValidationResult.getBinValidationInfo();
if(binInfo== null || (error != null && error.getTypeCode() == "3"))
{
	throw new Exception();
}
 
//Process Results
if(error == null){
	//DOTS Bin Validation Results	
}
//Process Errors
else{
	//DOTS Bin Validation Error Results	
}


Bin Validation PHP Code Snippets
<?php
// Set these values per web service <as needed>
$wsdlUrl = "https://trial.serviceobjects.com/bv/soap.svc?wsdl";

$params['BinNumber'] = $binNumber;
$params['LicenseKey'] = $licenseKey;

$soapClient = new SoapClient($wsdlUrl, array( "trace" => 1 ));
$result = $soapClient->ValidateBIN($params)->ValidateBINResult;
if (!isset($result->Error)) {
	foreach($result->BinValidationInfo; $k=>$v) {
		echo $k . ", " . $v;
	}
} else {
	foreach($result->Error as $k=>$v) {
		echo $k . ", " . $v;
	}
}
?>


Bin Validation RoR Code Snippets
    #Formats inputs into a hash to pass to Soap Client
		#Hash Keys must be named as they are shown here.
		message = 	{
					"BinNumber" => @request.binnumber,
					"LicenseKey" => @request.licensekey,
					}
		#Implemented to make the code more readable when accessing the hash			
		@bvresponse = :validate_bin_response
		@bvresult = :validate_bin_result
		@bvinfo = :bin_validation_info
		@bverror = :error

		#Set Primary and Backup URLs here as needed
		dotsBVPrimary = "https://trial.serviceobjects.com/bv/soap.svc?wsdl"
		dotsBVBackup = "https://trial.serviceobjects.com/bv/soap.svc?wsdl"

		begin
			#initializes the soap client. The convert request keys global is necessary to receive a response from the service.
			client = Savon.client(	wsdl: dotsBVPrimary,
									element_form_default: :qualified,
									convert_request_keys_to: :camelcase
								 )
			#Calls the operation with given inptus and converts response to a hash.
			response = client.call(:validate_bin, message: message).to_hash

			#Checks to see what results came back from the service
			processresults(response)			
			
		#If an error occurs during the call, this will use backup url and attempt to retrieve data.
		rescue Savon::Error => e
			begin
			backupclient = Savon.client(	wsdl: dotsBVBackup,
											element_form_default: :qualified,
											convert_request_keys_to: :camelcase
									   )

			#Sets the response to the backclient call to the operation and converts response to a hash.
			response = backupclient.call(:validate_bin, message: message).to_hash
			processresults(response)

			#If backup url failed, this will display the error received from the server
			rescue Savon::Error =>error
			end
		end
	end
	private 
      #processes HTTParty response and uses hash names to display
	def processresults(response)	
			#Processes Error Response from the web service		
			#Processes a valid response from the web service
	end


BIN Validation Python Code Snippet
    mBinNumber =  BinNumber.get()
    if mBinNumber is None or  mBinNumber == "":
         mBinNumber = " "
    mLicenseKey = LicenseKey.get()
    if mLicenseKey is None or mLicenseKey == "":
        mLicenseKey = " "

    #Set the primary and backup URLs as needed
    primaryURL = 'https://trial.serviceobjects.com/bv/soap.svc?wsdl'
    backupURL = 'https://trial.serviceobjects.com/bv/soap.svc?wsdl'

    #This block of code calls the web service and prints the resulting values to the screen
    try:
        client = Client(primaryURL)
        result = client.service.ValidateBIN(BinNumber= mBinNumber, LicenseKey=mLicenseKey)
        #Handel response and check for errors
    
    #Tries the backup URL if the primary URL failed
    except:
        try:
            client = Client(backupURL)
            result = client.service.ValidateBIN(BinNumber= mBinNumber, LicenseKey=mLicenseKey)
            #Handel response and check for errors


        #If the backup call failed then this will display an error to the screen
        except:
            Label(swin.window, text='Error').pack()
            print (result)


BIN Validation ColdFusion Code Snippet
<!--Makes Request to web service --->
<!--Old Service Reference: https://trial.serviceobjects.com/bv/BinValidation.asmx?WSDL --->
<cfscript>
	try
	{
		if (isDefined("form.Action") AND Action neq "")
		{
			wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/bv/soap.svc?wsdl");							  
			outputs = wsresponse.validateBin("#BinNumber#" ,"#LicenseKey#");
		}
	}
	catch(any Exception)
	{
		try
			{
				if (isDefined("form.Action") AND Action neq "")
				{
					wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/bv/soap.svc?wsdl");							  
					outputs = wsresponse.validateBin("#BinNumber#" ,"#LicenseKey#");
				}
			}
			catch(any Exception)	
				{
		  		 writeoutput("An Error Has Occured. Please Reload and try again #Exception.message#");		  		 
		 		}
	 }
</cfscript>


BIN Validation VB Code Snippet
Try
    Dim ws As New BV.DOTSBinValidationSoapClient
    Dim response As BV.BinValidationResult
    response = ws.ValidateBIN(BIN.Text, LicenseKey.Text)
    If (response.Error Is Nothing) Then
        ProcessValidResponse(response.BinValidationInfo)
    Else
        ProcessErrorResponse(response.Error)
    End If

Catch er As Exception
    Try
        Dim ws As New BV.DOTSBinValidationSoapClient
        Dim response As BV.BinValidationResult
        response = ws.ValidateBIN(BIN.Text, LicenseKey.Text)
        If (response.Error Is Nothing) Then
            ProcessValidResponse(response.BinValidationInfo)
        Else
            ProcessErrorResponse(response.Error)
        End If
    Catch ex As Exception
        resultsLabel.Visible = True
        resultsLabel.Text = ex.Message
    End Try
End Try


BIN Validation Apex Code Snippet
wwwServiceobjectsCom.BinValidationResult result;
try{
wwwServiceobjectsCom.DOTSBinValidationSoap client = new wwwServiceobjectsCom.DOTSBinValidationSoap();
result = client.ValidateBIN([BINNumber], [LicenseKey]);
}
catch(Exception ex){
 //If the first request failed try the failover endpoint
wwwServiceobjectsCom.DOTSBinValidationSoap backupClient = new wwwServiceobjectsCom.DOTSBinValidationSoap();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'https://trial.serviceobjects.com/BV/api.svc/soap';
result = backupClient.ValidateBIN([BINNumber], [LicenseKey]);
}


BIN Validation TSQL Code Snippet
SET @requestBody ='<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'+
				   '<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">'+
				   '<ValidateBIN xmlns="http://www.serviceobjects.com/">'+
				   '<BinNumber>' + @bin + '</BinNumber>'+
				   '<LicenseKey>' + @key + '</LicenseKey>'+
				   '</ValidateBIN>'+
				   '</s:Body>'+
				   '</s:Envelope>'

SET @requestLength = LEN(@requestBody)
	--If a production key is purchased, this will execute the failover 
IF @isLiveKey = 1
BEGIN
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://trial.serviceobjects.com/bv/BinValidation.asmx', false
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'trial.serviceobjects.com'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/ValidateBIN"'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
	EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
	EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
	EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://trial.serviceobjects.com/bv/BinValidation.asmx', false
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'trial.serviceobjects.com'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/ValidateBIN"'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
		EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
		EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
		EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
	END
END



BIN Validation C# Code Snippet
//encodes the URLs for the get Call. Set the primary and back urls as necessary
string primaryurl = "https://trial.serviceobjects.com/BV/web.svc/json/ValidateBIN_V2?BinNumber=" + bin + "&LicenseKey=" + licensekey;
string backupurl = "https://trial.serviceobjects.com/BV/web.svc/json/ValidateBIN_V2?BinNumber=" + bin + "&LicenseKey=" + licensekey;
BVResponse_Rest.BinValidationResult wsresponse = httpGet(primaryurl);

//checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
if (wsresponse == null || (wsresponse.Error != null && wsresponse.Error.TypeCode == "3"));
{
    wsresponse = httpGet(backupurl);
}
if (wsresponse.Error != null)
{
    ProcessErrorResponse(wsresponse.Error);
}
else
{
    ProcessSuccessfulResponse(wsresponse.BinValidationInfo);
}


BIN Validation Java Rest Code Snippet
JSONObject results = RestClient(mainURL);	
try {
	if (ErrorMessages != null || (results.getJSONObject("BinValidationResult").has("Error") && results.getJSONObject("BinValidationResult").getJSONObject("Error").get("DescCode") == "3")) {
		// BACKUP
		results = RestClient(backupURL);
	}
} catch (JSONException e) {
	// TODO Auto-generated catch block
	e.printStackTrace();
}

return results;


BIN Validation PHP Code Snippet
$URL = "https://trial.serviceobjects.com/BV/web.svc/json/ValidateBIN_V2?BinNumber=".urlencode($BIN)."&LicenseKey=".urlencode($LicenseKey);
//use backup url once given purchased license key
$backupURL = "https://trial.serviceobjects.com/BV/web.svc/json/ValidateBIN_V2?BinNumber=".urlencode($BIN)."&LicenseKey=".urlencode($LicenseKey);
try{
	// Get cURL resource
	$curl = curl_init();
	curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $URL, CURLOPT_USERAGENT => 'Service Objects BIN Validation'));
	curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
	// Send the request & save response to $resp
	$resp = curl_exec($curl);
	
	// Close request to clear up some resources
	if($resp == false)
	{
		echo "IN back up block";
		curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $backupURL, CURLOPT_USERAGENT => 'Service Objects BIN Validation'));
		curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
		// Send the request & save response to $resp
		$resp = curl_exec($curl);
		if($resp == false)
		{
			echo "<b> Both rest calls failed </b>";
			curl_close($curl);
			return;
		}
	}


Bin Validation RoR Rest Code Snippets
      @request = Request.find(params[:id])
      #This sets the default timeout for HTTParty get operation. This must be set in order to use the gem
      default_timeout = 10
      binnumber = @request.binnumber
      licensekey = @request.licensekey
      #Set Primary and Backup URLs as needed. This method encodes and standardizes the URI to pass to the REST service.
      primaryURL = URI.encode("https://trial.serviceobjects.com/BV/web.svc/json/ValidateBIN_V2?BinNumber=" + binnumber + "&LicenseKey=" + licensekey)
      backupURL = URI.encode("https://trial.serviceobjects.com/BV/web.svc/json/ValidateBIN_V2?BinNumber=" + binnumber + "&LicenseKey=" + licensekey)
      
      #These are set to access the hash that is returned
      @bvresult ="BinValidationResult"
      @bvinfo = "BinValidationInfo"
      @bverror = "Error"
        #Begins the call the RESTful web service
      begin
        response = HTTParty.get(primaryURL, timeout: default_timeout)
        #processes the response to display to the screen
        
        #Passes the response returned from HTTParty and processes them depending on the results
        processresults(response)
       rescue StandardError => e
       		begin
       		#uses the backupURl in the event that the service encountered an error
       		response = HTTParty.get(backupURL, timeout: default_timeout)
          
          #processes the response returned from using the backupURL
       		processresults(response)
          #If the backup url railed this will raise an error and display the 
          #error message returned from the HTTParty gem.
       		rescue StandardError => error
       			@status = error.message
       			@displaydata = {"Error" => "A Big Error Occured"}
       		end
      end


BIN Validation Python Rest CodeSnippet
    #Set the primary and backup URLs as necessary
    primaryURL = 'https://trial.serviceobjects.com/BV/web.svc/xml/ValidateBIN_V2?'
    backupURL = 'https://trial.serviceobjects.com/BV/web.svc/xml/ValidateBIN_V2?'
    #The Requests package allows the user to format the path parameters like so instead of having to manually insert them into the URL
    inputs = {'BinNumber': mBinNumber, 'LicenseKey': mLicenseKey}
    try:
        result = requests.get(primaryURL, params=inputs)
        #Parses the XML response from the service into a python dictionary type
        outputs = xmltodict.parse(result.content)
        #checks the output for Errors and displays the info accordingly
        if 'Error' in outputs['BinValidationResult']:
            #loops through the response from the service and prints the values to the screen.
            for key, value in outputs['BinValidationResult']['Error'].iteritems():
                Label(swin.window, text=str(key) + " : " + str(value)).pack()
        #Prints a valid response if one was received from the service
        else:
            for key, value in outputs['BinValidationResult']['BinValidationInfo'].iteritems():
                Label(swin.window, text=str(key) + " : " + str(value)).pack()
    #Attempts to use the backupURL if the call to the primary URL failed
    except:
        try:
            result = requests.get(backupURL, params=inputs)
            #Parses the XML response from the service into a python dictionary type
            outputs = xmltodict.parse(result.content)
            #checks the output for Errors and displays the info accordingly
            if 'Error' in outputs['BinValidationResult']:
                #loops through the response from the service and prints the values to the screen.
                for key, value in outputs['BinValidationResult']['Error'].iteritems():
                    Label(swin.window, text=str(key) + " : " + str(value)).pack()
            #Prints a valid response if one was received from the service
            else:
                for key, value in outputs['BinValidationResult']['BinValidationInfo'].iteritems():
                    Label(swin.window, text=str(key) + " : " + str(value)).pack()


BIN Validation ColdFusion Rest Code Snippet
<!--Makes Request to web service --->
<cfIf isDefined("form.Action") AND Action neq "" >
	<cftry>
		<cfset primaryURL = "https://trial.serviceobjects.com/BV/web.svc/xml/ValidateBIN_V2?BinNumber=#BinNumber#&LicenseKey=#LicenseKey#">
		<cfhttp url="#primaryURL#" method="get" result="response">
		<cfset outputs = XmlParse(response.FileContent)>
		<cfcatch>
			<cftry>
				<cfset backupURL = "https://trial.serviceobjects.com/BV/web.svc/xml/ValidateBIN_V2?BinNumber=#BinNumber#&LicenseKey=#LicenseKey#">
				<cfhttp url="#backupURL#" method="get" result="response">
				<cfset outputs = XmlParse(response.FileContent)>				
				<cfcatch >
					<cfoutput >
						The Following Error Occured: #response.StatusCode#
					</cfoutput>
				</cfcatch>
			</cftry>
		</cfcatch>
	</cftry>
</cfif>


BIN Validation VB Rest Code Snippet
Try
    'encodes the URLs for the get Call. Set the primary and back urls as necessary
    Dim primaryurl As String = "https://trial.serviceobjects.com/BV/web.svc/json/ValidateBIN_V2?BinNumber=" & bin + "&LicenseKey=" & licensekey
    Dim backupurl As String = "https://trial.serviceobjects.com/BV/web.svc/json/ValidateBIN_V2?BinNumber=" & bin + "&LicenseKey=" & licensekey
    Dim wsresponse As BVResponse.BinValidationResult = httpGet(primaryurl)

    'checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
    If wsresponse Is Nothing OrElse (wsresponse.[Error] IsNot Nothing AndAlso wsresponse.[Error].TypeCode = "3") Then
        wsresponse = httpGet(backupurl)
    End If
    If wsresponse.[Error] IsNot Nothing Then
        ProcessErrorResponse(wsresponse.[Error])
    Else
        ProcessSuccessfulResponse(wsresponse.BinValidationInfo)

    End If
Catch ex As Exception
    'Displays the relevant error mesasge if both backup and primary urls failed.
    StatusLabel.Text = ex.Message
    StatusLabel.Visible = True
End Try


BIN Validation TSQL Rest Code Snippet
IF @isLiveKey = 1
BEGIN
	SET @sUrl = 'https://trial.serviceobjects.com/BV/web.svc/xml/ValidateBIN_V2?BinNumber=' + @bin + '&LicenseKey=' + @key
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sUrl, false
	EXEC sp_OAMethod @obj, 'send'
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		SET @sBackupUrl = 'https://trial.serviceobjects.com/BV/web.svc/xml/ValidateBIN_V2?BinNumber=' + @bin + '&LicenseKey=' + @key
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sBackupUrl, false
		EXEC sp_OAMethod @obj, 'send'
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
	END
END

You can find and download full sample code to our services in various languages (PHP, JAVA and C#) by clicking here. Below is a C# version.

If you are looking for a particular integration not listed in our documentation please contact us at support@serviceobjects.com.

C#
using System;
using System.Collections.Generic;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
namespace ServiceObjects
{
    public partial class _Default : System.Web.UI.Page
    {
        // Create FailOver Constant for redundency in case the primary URL is down
        private const String FailOver = "https://trial.serviceobjects.com/BV/web.svc/json/ValidateBIN_V2";
        // Create Proxy Object to handle request to service
        private com.serviceobjects.trial.DOTSBinValidation DOTSBinValidation;
        // Create Result Object to handle response from service
        private com.serviceobjects.trial.BinValidationResult BankInfo;
        protected void Page_Load(object sender, EventArgs e)
        {
            DOTSBinValidation = new ServiceObjects.com.serviceobjects.trial.DOTSBinValidation();
            BankInfo = null;
            ResultLabel.Text = "";
            ResultLabel.Visible = false;
        }
        protected void btn_GO_Click(object sender, ImageClickEventArgs e)
        {
            try
            {
                try
                {
                    // Make initial request to Bin Validation Service
                    BankInfo = DOTSBinValidation.ValidateBIN(BinNumber.Text, LicenseKey.Text);
                }
                catch (Exception ex)
                {
                    // If there was an error in making initial call, switch to failover and try again. Insert any failover logic here
                    DOTSBinValidation.Url = FailOver;
                    BankInfo = DOTSBinValidation.ValidateBIN(BinNumber.Text, LicenseKey.Text);
                }
                if (BankInfo.Error == null)
                {
                    // No errors found, display results below
                    ResultLabel.Text += "<b>Bin Validation Results:</b><table border='1'>";
                    ResultLabel.Text += "<tr><td>BIN:</td><td>" + BankInfo.BinValidationInfo.BIN + "</td></tr>";
                    ResultLabel.Text += "<tr><td>Bank Name:</td><td>" + BankInfo.BinValidationInfo.BankName + "</td></tr>";
                    ResultLabel.Text += "<tr><td>Payment Method:</td><td>" + BankInfo.BinValidationInfo.PaymentMethod + "</td></tr>";
                    ResultLabel.Text += "<tr><td>Card Type:</td><td>" + BankInfo.BinValidationInfo.CardType + "</td></tr>";
                    ResultLabel.Text += "<tr><td>Country Abbreviation:</td><td>" + BankInfo.BinValidationInfo.CountryAbbreviation + "</td></tr>";
                    ResultLabel.Text += "<tr><td>Country Name:</td><td>" + BankInfo.BinValidationInfo.CountryName + "</td></tr>";
                    ResultLabel.Text += "<tr><td>Phone Numbers:</td><td>" + BankInfo.BinValidationInfo.PhoneNumbers + "</td></tr>";
                    ResultLabel.Text += "</table>";
                    ResultLabel.Visible = true;
                }
                else
                {
                    // There were errors found, lets display them here
                    ResultLabel.Text += "<b>Errors Found!</b><table border='1'>";
                    ResultLabel.Text += "<tr><td>Error Description:</td><td>" + BankInfo.Error.Desc + "</td></tr>";
                    ResultLabel.Text += "<tr><td>Error Code:</td><td>" + BankInfo.Error.DescCode + "</td></tr>";
                    ResultLabel.Text += "</table>";
                    ResultLabel.Visible = true;
                }
            }
            catch (Exception ex)
            {
                // Unable to create object, display errors below
                ResultLabel.Text = ex.Message;
                ResultLabel.Visible = true;
            }
        }
    }
}





XMLRequest
https://trial.serviceobjects.com/BV/web.svc/xml/ValidateBIN_V2?BinNumber=string&LicenseKey=string


XML Response
<BinValidationResultV2 xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<BinValidationInfoV2>
<Status>OK</Status>
<BIN>426684</BIN>
<Brand>VISA</Brand>
<CardType>CREDIT</CardType>
<SubType>CLASSIC</SubType>
<Bank>CHASE BANK USA, N.A.</Bank>
<Country>UNITED STATES</Country>
<CountryISO2>US</CountryISO2>
<Phone/>
<Warnings/>
<Notes/>
<InformationComponents/>
</BinValidationInfoV2>
</BinValidationResultV2>


JSON Request
https://trial.serviceobjects.com/BV/web.svc/json/ValidateBIN_V2?BinNumber=string&LicenseKey=string


JSON Response
{"BinValidationInfoV2":{"Status":"OK","BIN":"426684","Brand":"VISA","CardType":"CREDIT","SubType":"CLASSIC","Bank":"CHASE BANK USA, N.A.","Country":"UNITED STATES","CountryISO2":"US","Phone":"","Warnings":[],"Notes":[],"InformationComponents":[]},"DEBUG":""}




Request Types

DOTS BIN Validation is a public XML web service that supports SOAP(1.1 and 1.2), POST, and GET request methods. A request type is just the type of web (HTTP) request used to interact with our web services. 
GET - All of the input data is in the query string appended to the URL. The response is simple XML.
POST - The input parameters are in the body of the request instead of the query string. The response is simple XML.
SOAP - The input parameters are in an XML SOAP message contained within the body of the request. The response is an XML SOAP message.

Analysis of Request Types

GET is the easiest method to implement by hand because you just set up the URL and query string. It is also easy to debug because you can test the URL + query string in a web browser and see the output.
POST is probably the best method to implement by hand because you do not have to know the specifics of SOAP, and is a little cleaner than passing input parameters in the query string via GET.
SOAP is the best method if you are using a platform that supports SOAP. In many programming environments you can the service's WSDL file (https://trial.serviceobjects.com/bv/soap.svc?wsdl) to create a proxy class to help you interact with the web service. In this case you only have to create an instance of the proxy and use its methods. This completely abstracts the programmer from any complications like sending/receiving web requests/responses as well as any XML parsing. This is typically available in newer environments like PHP version 5, ColdFusion version 7, .NET, etc. Older languages like PHP version 4 and ColdFusion version 5 will require the use of GET or POST.

XML Parsing

If you are not using an environment that provides a proxy class for you to use, then you will have to parse XML. If you do have a proxy, then it uses an XML parser behind the scenes for you. Although XML parsing can be done without a parser, most programming environments provide easy access to several standard ones. We strongly recommend that you take advantage of an XML parser. These parsers may take a few more minutes to integrate if the developer is not familiar with them, but will give your application an added level of security against improper parsing. Without them it is very difficult, even for skilled programmers to write robust code that can handle all cases of XML properly. Because we have very consistent XML you could get away without this extra precaution, but we suggest you use an XML parser anyway to ensure your application is of the highest quality.

List of Operations

Every web service has operations that it offers to subscribers. These operations, also called methods, contain different functionality and return different outputs. DOTS BIN Validation has just one operation:

ValidateBIN_V2 (Recommended Operation) – Uses the provided BIN to retrieve charge card and bank information. If the specified BIN is not found, an error will be returned requesting a valid BIN.
ValidateBIN 
– Uses the provided BIN to retrieve charge card and bank information. If the specified BIN is not found, an error will be returned requesting a valid BIN.

This operation will be described in detail later in this document.

Operation Definitions

This section defines the input, output and behavior of the operations in DOTS BIN Validation.

ValidateBIN 

ValidateBIN Inputs

Name

Type

Description

BinNumber

String

The six-digit BIN you wish to validate. The BIN is the first six digits of a given charge card number.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/ecommerce/bin-validation

ValidateBIN Outputs

If no errors are encountered a BinValidationInfo element will be returned with the following information. If there is an error, an Error object will be returned (explained in next section).

Name

Type

Description

BIN

String

The input BIN.

BankName

String

The name of the bank that issued the charge card.

PaymentMethod

String

Credit, Debit, or Prepaid.

CardType

String

Description of the type of card (i.e. Classic, Platinum, etc.)

CountryAbbreviation

String

Abbreviation of the country where the issuing bank is located.

CountryName

String

Name of the country where the issuing bank is located.

PhoneNumbers

String

List of service phone numbers for the charge card.

DEBUG

String

Unused in this service.

ValidateBIN_V2 (Recommended Operation)

ValidateBIN_V2 Inputs

Name

Type

Description

BinNumber

String

The six-digit BIN you wish to validate. The BIN is the first six digits of a given charge card number.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/ecommerce/bin-validation

ValidateBIN_V2 Outputs

If no errors are encountered a BinValidationInfo element will be returned with the following information. If there is an error, an Error object will be returned (explained in next section).

Name

Type

Value

Description

StatusString"OK" or "NotFound"A value indicating whether or not the input BIN was found in our system.

BIN

String

Varies

The input BIN.

BankName

String

Varies

The name of the bank that issued the charge card.

BrandStringVariesThe brand associated with the given BIN. (i.e. Mastercard, Visa, Discover etc)

CardType

String

Varies

Credit, Debit, or Prepaid.

SubType

String

Varies

Description of the type of card (i.e. Classic, Platinum, etc.)

Country

String

Varies

Name of the country where the issuing bank is located.

CountryISO2

String

Varies

Name of the country where the issuing bank is located.

Phone

String

Varies

List of service phone numbers associated with the charge card

WarningsCode[]VariesA series of codes and warning descriptions that correspond to different information given about the BIN. See below for a table of codes and descriptions
NotesCode[]VariesA series of codes and note descriptions that provide additional information about the BIN. (There are currently no note codes associated with this operation)
InformationComponentsInformationComponent[]VariesA array of name value pairs with additional fields and information about the BIN.(There are currently no Information Components in use in this operation)

DEBUG

String


Unused in this service.

Code

NameTypeValuesDescription
CodeIntVariesA code that will correspond to the given description
DescriptionStringVariesA description containing additional information.

InformationComponent

NameTypeValuesDescription
NameStringVariesThe variable name of the Name-Value pair that is to be returned.
ValueStringVariesThe resulting value of the of the variable returned in the "Name".

Warnings*

CodeDescription
1Bank Information Not Found
2No Card Type Found
3No Country Associated with BIN

*New Warnings will be added in the future to the BIN Validation service


Errors

Generally, an error is anything that happens during a run of DOTS BIN Validation that causes the service to fail. If an error occurs, an XML error message, similar to the one below, will result instead of the BinValidationInfo output described above:


Example:

*Error!*

  <Type>Authorization</Type>
  <TypeCode>1</TypeCode>
  <Desc>Your license key does not work on this service.*</Desc>
  <DescCode>8</DescCode>

There are four error types described below.

Error Types

Type

Type Code

Billable

Standard Across All Gen2 Web Services

Authorization

1

No

Yes

User Input

2

Yes

No

Service Objects Fatal

3

No

Yes

Domain Specific

4

Yes

No

Error type 1: Authorization

Theses are standard to all Generation 2 DOTS Web Services.

DescCode

Desc

0

Unknown authorization error.

1

Please provide a valid license key for this web service.

2

The daily allowable number of transactions for this license key has been exceeded.

3

The monthly allowable number of transactions for this license key has been exceeded.

4

The total allowable number of transactions for this license key has been exceeded.

5

There are not enough transactions available. Check your daily/monthly transaction limits.

6

This license key has not yet been activated.

7

This license key has expired.

8

Your license key does not work on this service.

Error type 2: User Input

User Input errors are caused when a user inputs an invalid value or fails to provide a certain input field altogether. If a developer creates a request and mistypes a parameter name, it will probably cause a User Input Error.

DescCode

Desc

1

"You must input a license key in the LicenseKey field."

2

"Improper BIN format. Please input a valid BIN."

Error type 3: Service Objects Fatal

The Desc will always be the same and the DescCode has no meaning. This is standard to all Generation 2 DOTS Web Services. This is a rare error that signals either a bug in the DOTS BIN Validation service, or a Network/Connectivity issue.

DescCode

Desc

1

"Unhandled error. Please contact Service Objects."

Error type 4: Domain Specific

Domain specific errors represent the common errors seen in Service Objects services. Domain Specific errors indicate that the service completed successfully but the result is not good.

DescCode

Desc

1

"BIN not found. Please input a valid BIN."

2

"Bank information is currently unavailable."

Conclusion

Service Objects is pleased to offer you a free trial of DOTS BIN Validation. 


Other technical questions or concerns can be directed to support@serviceobjects.com.

If you are interested in purchasing DOTS BIN Validation, please contact sales@serviceobjects.com.


  
We want to hear from you! We're always looking to improve our developer guides. 
Please email your suggestions to devguidefeedback@serviceobjects.com.

  • No labels