BinDB Web Portal Documentation

API Technical Documentation

Contents of this document:

1.Introduction to BIN Identification
2.What is the Web Portal?
3.Features
4.API Usage
5.API XML Response Structure
6 API JSON Response Structure
7.API Errors
8.Conclusion

1. Introduction to BIN Identification

In some ways the Bank Identification Number (BIN) is similar to a vehicle's license plate. The BIN/IIN Number carry encoded details about a bank payment card’s origins and type. The first six digits of any bank card number carry information about the type, country, bank and level of the card. With the Web Portal our clients gain valuable insight on online payments and their potential customers. Being able to determine the issuing bank and credit level information about a credit card used in an online payment gives our clients a great opportunity to assess the risk of any online transaction. The client can build their payment processing logic based on the checks performed using the BIN Database.

2. What is the BinDB Web Portal?

BinDB Web Portal is an online system which provides businesses with an online interface where they can perform real-time BIN identification. A manual search engine allows you to look up any BIN number in the database and the API helps integrate our service in your company software. A multi-user support allows you to create sub-users for your employees and keep a historical records of all queries performed through the manual search or the API. The portal can be linked to either the Premium Database or the Ultimate Database depending on the types of transaction and level of coverage you need.

3. Features

BinDB's Premium Database License allows our clients do the following using only the first six digits of any credit card number.

Determine if a card is a VISA, MASTERCARD, AMERICAN EXPRESS or any other card brand.
Determine if a card is a Debit card or a Credit card.
Find the level of the card such as Business, Platinum, Gold etc.
Detect Prepaid, Gift and Virtual Cards.
Find which bank has issued the card.
Find from which country the card was issued.
Find the issuing contact phone and website of the bank which issued the card.

4. API Request Usage

The API system allows you to automate BIN identification via a simple HTTP GET request. Inside your Online Portal you can find your API key which is used to secure the search requests. An example of the the API request can be found below:

https://apiserver/api.php?api_key=[API_KEY]&bin=[BIN]

Example

https://apiserver/api.php?api_key=68Y6NV485VY4596BN4856Y&bin=546616

An XML Schema of the API’s response can be found in the documentation archive. A detailed description of the fields returned can be seen in the table below:

Input Parameters

Field Name	Type	Description	Example
API_KEY	String	The key to use to authenticate to the service.	68Y6NV485VY4596BN4856Y
BIN	String	The first six digits of a card number are known as the issuer identification number	546616

Where: - API is your API key - BIN is the Bank Identification Number you want to check. Once an HTTP get request is made with the correct API key, the system will return the results in an XML format. You can find an example XML response in the next section “API XML Response Structure”

API-Response XML Schema.xsd - A XSD Schema file containing description of the fields returned in the API XML response.

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="result">
    <xs:complexType>
      <xs:sequence>
        <xs:element type="xs:int" name="bin"/>
        <xs:element type="xs:string" name="brand"/>
        <xs:element type="xs:string" name="bank"/>
        <xs:element type="xs:string" name="type"/>
        <xs:element type="xs:string" name="level"/>
        <xs:element type="xs:string" name="isocountry"/>
        <xs:element type="xs:string" name="country_iso"/>
        <xs:element type="xs:string" name="country2_iso"/>
        <xs:element type="xs:short" name="country3_iso"/>
        <xs:element type="xs:anyURI" name="www"/>
        <xs:element type="xs:string" name="phone"/>
        <xs:element type="xs:string" name="info"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Download Schema.xsd

5. API XML Response Result Structure

The API system returns results in XML format which is easy to parse in a variety of programming languages and platforms. A sample XML reply from the API would be:

<?xml version="1.0" encoding="utf-8" ?> 
<result>
		 <bin>546616</bin>
		 <brand>MASTERCARD</brand>
		 <bank>CITIBANK N.A.</bank>
		 <type>CREDIT</type>
		 <level>WORLD ELITE</level>
		 <isocountry>UNITED STATES</isocountry>
		 <info>AADVANTAGE EXECUTIVE</info>
		 <country_iso>US</country_iso>
		 <country2_iso>USA</country2_iso>
		 <country3_iso>840</country3_iso>
		 <www>WWW.CITI.COM</www>
		 <phone>1-888-776-2484</phone>
</result>

6. API JSON Response Result Structure

The API system also can return results in JSON format. A sample JSON reply from the API would be:

{
	"bin": "543210",
	"brand": "MASTERCARD",
	"bank": "NATIONAL PENN BANK",
	"type": "",
	"level": "",
	"isocountry": "UNITED STATES",
	"info": "877-866-7827 OR 800-822-3321",
	"country_iso": "US",
	"country2_iso": "USA",
	"country3_iso": "840",
	"www": "www.natpennbank.com",
	"phone": "+1 610 369 6128"
}

Result Fields

Field Name	Length	Type	Description	Example
BIN	6	Numeric	The first six digits of a card number are known as the issuer identification number (IIN) aka Bank Identification Number (BIN)	546616
BRAND	128	String	Card brand specifies the card company/vendor which issued the card i.e. Visa/MasterCard/AMEX etc.	MASTERCARD
BANK NAME	128	String	Name of the bank or financial institution which issued the card.	CITIBANK N.A.
TYPE	32	String	Type of card. i.e. CREDIT/DEBIT	CREDIT
LEVEL	32	String	The level field specifies of a card is PREPAID/GOLD/GIFT/BUSINESS/ELECTRON etc.	WORLD ELITE
ISOCOUNTRY	64	String	Full name of the country of origin e.g. “United States”	UNITED STATES
INFO	128	String	Additional information if available. Usually contact or alternative contact information about the issuing bank.	AADVANTAGE EXECUTIVE
COUNTRY_ISO	2	Char	Two letter ISO country code.	US
COUNTRY2_ISO	3	Char	Three letter ISO country code.	USA
COUNTRY3_ISO	3	Numeric	Numeric ISO country code.	840
WWW	128	String	URL Address of the issuing bank's main website.	WWW.CITI.COM
PHONE	128	String	Contact phone number of the issuing bank. Usually the main branch phone.	1-888-776-2484

7. API Response Errors

In case of an error the API returns an XML response containing the error message. The <error></error> XML tags are returned without any other fields in the XML response. Below you can find a description of all possible error messages that could be returned:

Result Errors

ID	Cause	Resolution
100	API key required	You need to submit the API key to our API for each request. API key can be found in your Web Portal -> API -> API Access section.
101	BIN not specified	BIN field is required for successful search.
102	Invalid API key	Please check that you are submitting your API key exactly as in your account.
103	IP Address is not allowed	You need to allow access to your server or computer's IP address in your Web Portal -> API Access section.
104	Unspecified Error	If you experience this error, please contact our support for further investigation.
105	BIN Not Valid	BIN must be exactly six digits long for correct idenfitication.
106	BIN Not Found	The submitted BIN has not been found in our database. Please report to support for investigation.
107	Subscription Expired	Your membership has expired, please go to Membership section for instructions how to renew your membership.

8. Conclusion

Other technical questions can be directed to sales@bindb.com. If you are interested in purchasing Premium License, please contact our order page.